diff options
| author | Daniel Thorpe <1077065+dantho281@users.noreply.github.com> | 2021-02-11 02:25:57 +0000 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-02-11 02:25:57 +0000 |
| commit | e88fba68357181bd54fcc7489cbba08780cee6cd (patch) | |
| tree | b67e88b1208fa835edf0420a42dd2b624ec2105b | |
| parent | dab473bfd04ab2930c043b853ba9995d1ff335e6 (diff) | |
| parent | f33b0c78b07c80998d2c0e64d6a20bcb109f6db5 (diff) | |
| download | vyos-documentation-e88fba68357181bd54fcc7489cbba08780cee6cd.tar.gz vyos-documentation-e88fba68357181bd54fcc7489cbba08780cee6cd.zip | |
Merge pull request #1 from vyos/master
Update fork
273 files changed, 13325 insertions, 5709 deletions
diff --git a/ci/vale/Google/AMPM.yml b/.github/styles/Google/AMPM.yml index fbdc6e4f..fbdc6e4f 100644 --- a/ci/vale/Google/AMPM.yml +++ b/.github/styles/Google/AMPM.yml diff --git a/ci/vale/Google/Acronyms.yml b/.github/styles/Google/Acronyms.yml index f41af018..f41af018 100644 --- a/ci/vale/Google/Acronyms.yml +++ b/.github/styles/Google/Acronyms.yml diff --git a/ci/vale/Google/Colons.yml b/.github/styles/Google/Colons.yml index 9a4b4b4a..9a4b4b4a 100644 --- a/ci/vale/Google/Colons.yml +++ b/.github/styles/Google/Colons.yml diff --git a/ci/vale/Google/Contractions.yml b/.github/styles/Google/Contractions.yml index 905a39f4..905a39f4 100644 --- a/ci/vale/Google/Contractions.yml +++ b/.github/styles/Google/Contractions.yml diff --git a/ci/vale/Google/DateFormat.yml b/.github/styles/Google/DateFormat.yml index e9d227fa..e9d227fa 100644 --- a/ci/vale/Google/DateFormat.yml +++ b/.github/styles/Google/DateFormat.yml diff --git a/ci/vale/Google/Ellipses.yml b/.github/styles/Google/Ellipses.yml index 436e6177..436e6177 100644 --- a/ci/vale/Google/Ellipses.yml +++ b/.github/styles/Google/Ellipses.yml diff --git a/ci/vale/Google/EmDash.yml b/.github/styles/Google/EmDash.yml index c6018db1..c6018db1 100644 --- a/ci/vale/Google/EmDash.yml +++ b/.github/styles/Google/EmDash.yml diff --git a/ci/vale/Google/EnDash.yml b/.github/styles/Google/EnDash.yml index 194876aa..194876aa 100644 --- a/ci/vale/Google/EnDash.yml +++ b/.github/styles/Google/EnDash.yml diff --git a/ci/vale/Google/Exclamation.yml b/.github/styles/Google/Exclamation.yml index c4db380b..c4db380b 100644 --- a/ci/vale/Google/Exclamation.yml +++ b/.github/styles/Google/Exclamation.yml diff --git a/ci/vale/Google/FirstPerson.yml b/.github/styles/Google/FirstPerson.yml index d2290611..d2290611 100644 --- a/ci/vale/Google/FirstPerson.yml +++ b/.github/styles/Google/FirstPerson.yml diff --git a/ci/vale/Google/Gender.yml b/.github/styles/Google/Gender.yml index c8486181..c8486181 100644 --- a/ci/vale/Google/Gender.yml +++ b/.github/styles/Google/Gender.yml diff --git a/ci/vale/Google/GenderBias.yml b/.github/styles/Google/GenderBias.yml index 261cfb66..261cfb66 100644 --- a/ci/vale/Google/GenderBias.yml +++ b/.github/styles/Google/GenderBias.yml diff --git a/ci/vale/Google/HeadingPunctuation.yml b/.github/styles/Google/HeadingPunctuation.yml index 5c39abbf..5c39abbf 100644 --- a/ci/vale/Google/HeadingPunctuation.yml +++ b/.github/styles/Google/HeadingPunctuation.yml diff --git a/ci/vale/Google/Headings.yml b/.github/styles/Google/Headings.yml index 5afb968d..5afb968d 100644 --- a/ci/vale/Google/Headings.yml +++ b/.github/styles/Google/Headings.yml diff --git a/ci/vale/Google/Hyphens.yml b/.github/styles/Google/Hyphens.yml index f9779637..f9779637 100644 --- a/ci/vale/Google/Hyphens.yml +++ b/.github/styles/Google/Hyphens.yml diff --git a/ci/vale/Google/Latin.yml b/.github/styles/Google/Latin.yml index f032b349..f032b349 100644 --- a/ci/vale/Google/Latin.yml +++ b/.github/styles/Google/Latin.yml diff --git a/ci/vale/Google/LyHyphens.yml b/.github/styles/Google/LyHyphens.yml index d5b6a942..d5b6a942 100644 --- a/ci/vale/Google/LyHyphens.yml +++ b/.github/styles/Google/LyHyphens.yml diff --git a/ci/vale/Google/OptionalPlurals.yml b/.github/styles/Google/OptionalPlurals.yml index 7058932f..7058932f 100644 --- a/ci/vale/Google/OptionalPlurals.yml +++ b/.github/styles/Google/OptionalPlurals.yml diff --git a/ci/vale/Google/Ordinal.yml b/.github/styles/Google/Ordinal.yml index 8c429e0f..8c429e0f 100644 --- a/ci/vale/Google/Ordinal.yml +++ b/.github/styles/Google/Ordinal.yml diff --git a/ci/vale/Google/OxfordComma.yml b/.github/styles/Google/OxfordComma.yml index 98b07113..98b07113 100644 --- a/ci/vale/Google/OxfordComma.yml +++ b/.github/styles/Google/OxfordComma.yml diff --git a/ci/vale/Google/Parens.yml b/.github/styles/Google/Parens.yml index 3b8711d0..3b8711d0 100644 --- a/ci/vale/Google/Parens.yml +++ b/.github/styles/Google/Parens.yml diff --git a/ci/vale/Google/Passive.yml b/.github/styles/Google/Passive.yml index 3265890e..3265890e 100644 --- a/ci/vale/Google/Passive.yml +++ b/.github/styles/Google/Passive.yml diff --git a/ci/vale/Google/Periods.yml b/.github/styles/Google/Periods.yml index d24a6a6c..d24a6a6c 100644 --- a/ci/vale/Google/Periods.yml +++ b/.github/styles/Google/Periods.yml diff --git a/ci/vale/Google/Quotes.yml b/.github/styles/Google/Quotes.yml index 3cb6f1ab..3cb6f1ab 100644 --- a/ci/vale/Google/Quotes.yml +++ b/.github/styles/Google/Quotes.yml diff --git a/ci/vale/Google/Ranges.yml b/.github/styles/Google/Ranges.yml index 3ec045e7..3ec045e7 100644 --- a/ci/vale/Google/Ranges.yml +++ b/.github/styles/Google/Ranges.yml diff --git a/ci/vale/Google/Semicolons.yml b/.github/styles/Google/Semicolons.yml index bb8b85b4..bb8b85b4 100644 --- a/ci/vale/Google/Semicolons.yml +++ b/.github/styles/Google/Semicolons.yml diff --git a/ci/vale/Google/Slang.yml b/.github/styles/Google/Slang.yml index 63f4c248..63f4c248 100644 --- a/ci/vale/Google/Slang.yml +++ b/.github/styles/Google/Slang.yml diff --git a/ci/vale/Google/Spacing.yml b/.github/styles/Google/Spacing.yml index 5f209a9f..5f209a9f 100644 --- a/ci/vale/Google/Spacing.yml +++ b/.github/styles/Google/Spacing.yml diff --git a/ci/vale/Google/Spelling.yml b/.github/styles/Google/Spelling.yml index 57acb884..57acb884 100644 --- a/ci/vale/Google/Spelling.yml +++ b/.github/styles/Google/Spelling.yml diff --git a/ci/vale/Google/Units.yml b/.github/styles/Google/Units.yml index 220de3e9..220de3e9 100644 --- a/ci/vale/Google/Units.yml +++ b/.github/styles/Google/Units.yml diff --git a/ci/vale/Google/Will.yml b/.github/styles/Google/Will.yml index 128a9183..128a9183 100644 --- a/ci/vale/Google/Will.yml +++ b/.github/styles/Google/Will.yml diff --git a/ci/vale/Google/WordList.yml b/.github/styles/Google/WordList.yml index d5d6bea5..d5d6bea5 100644 --- a/ci/vale/Google/WordList.yml +++ b/.github/styles/Google/WordList.yml diff --git a/ci/vale/Google/meta.json b/.github/styles/Google/meta.json index 3ae5fb21..3ae5fb21 100644 --- a/ci/vale/Google/meta.json +++ b/.github/styles/Google/meta.json diff --git a/ci/vale/Google/vocab.txt b/.github/styles/Google/vocab.txt index e69de29b..e69de29b 100644 --- a/ci/vale/Google/vocab.txt +++ b/.github/styles/Google/vocab.txt diff --git a/ci/vale/VyOS/Terminology.yml b/.github/styles/VyOS/Terminology.yml index cd0c5089..cd0c5089 100644 --- a/ci/vale/VyOS/Terminology.yml +++ b/.github/styles/VyOS/Terminology.yml diff --git a/.github/vyos-linter.py b/.github/vyos-linter.py new file mode 100644 index 00000000..3dc7c2fc --- /dev/null +++ b/.github/vyos-linter.py @@ -0,0 +1,177 @@ +import os +import re +import ipaddress +import sys +import ast + +IPV4SEG = r'(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])' +IPV4ADDR = r'\b(?:(?:' + IPV4SEG + r'\.){3,3}' + IPV4SEG + r')\b' +IPV6SEG = r'(?:(?:[0-9a-fA-F]){1,4})' +IPV6GROUPS = ( + r'(?:' + IPV6SEG + r':){7,7}' + IPV6SEG, # 1:2:3:4:5:6:7:8 + r'(?:\s' + IPV6SEG + r':){1,7}:', # 1:: 1:2:3:4:5:6:7:: + r'(?:' + IPV6SEG + r':){1,6}:' + IPV6SEG, # 1::8 1:2:3:4:5:6::8 1:2:3:4:5:6::8 + r'(?:' + IPV6SEG + r':){1,5}(?::' + IPV6SEG + r'){1,2}', # 1::7:8 1:2:3:4:5::7:8 1:2:3:4:5::8 + r'(?:' + IPV6SEG + r':){1,4}(?::' + IPV6SEG + r'){1,3}', # 1::6:7:8 1:2:3:4::6:7:8 1:2:3:4::8 + r'(?:' + IPV6SEG + r':){1,3}(?::' + IPV6SEG + r'){1,4}', # 1::5:6:7:8 1:2:3::5:6:7:8 1:2:3::8 + r'(?:' + IPV6SEG + r':){1,2}(?::' + IPV6SEG + r'){1,5}', # 1::4:5:6:7:8 1:2::4:5:6:7:8 1:2::8 + IPV6SEG + r':(?:(?::' + IPV6SEG + r'){1,6})', # 1::3:4:5:6:7:8 1::3:4:5:6:7:8 1::8 + r':(?:(?::' + IPV6SEG + r'){1,7}|:)', # ::2:3:4:5:6:7:8 ::2:3:4:5:6:7:8 ::8 :: + r'fe80:(?::' + IPV6SEG + r'){0,4}%[0-9a-zA-Z]{1,}', # fe80::7:8%eth0 fe80::7:8%1 (link-local IPv6 addresses with zone index) + r'::(?:ffff(?::0{1,4}){0,1}:){0,1}[^\s:]' + IPV4ADDR, # ::255.255.255.255 ::ffff:255.255.255.255 ::ffff:0:255.255.255.255 (IPv4-mapped IPv6 addresses and IPv4-translated addresses) + r'(?:' + IPV6SEG + r':){1,4}:[^\s:]' + IPV4ADDR, # 2001:db8:3:4::192.0.2.33 64:ff9b::192.0.2.33 (IPv4-Embedded IPv6 Address) +) +IPV6ADDR = '|'.join(['(?:{})'.format(g) for g in IPV6GROUPS[::-1]]) # Reverse rows for greedy match + +MAC = r'([0-9A-F]{2}[:-]){5}([0-9A-F]{2})' + +NUMBER = r"([\s']\d+[\s'])" + + +def lint_mac(cnt, line): + mac = re.search(MAC, line, re.I) + if mac is not None: + mac = mac.group() + u_mac = re.search(r'((00)[:-](53)([:-][0-9A-F]{2}){4})', mac, re.I) + m_mac = re.search(r'((90)[:-](10)([:-][0-9A-F]{2}){4})', mac, re.I) + if u_mac is None and m_mac is None: + return (f"Use MAC reserved for Documentation (RFC7042): {mac}", cnt, 'error') + + +def lint_ipv4(cnt, line): + ip = re.search(IPV4ADDR, line, re.I) + if ip is not None: + ip = ipaddress.ip_address(ip.group().strip(' ')) + # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_private + if ip.is_private: + return None + if ip.is_multicast: + return None + if ip.is_global is False: + return None + return (f"Use IPv4 reserved for Documentation (RFC 5737) or private Space: {ip}", cnt, 'error') + + +def lint_ipv6(cnt, line): + ip = re.search(IPV6ADDR, line, re.I) + if ip is not None: + ip = ipaddress.ip_address(ip.group().strip(' ')) + if ip.is_private: + return None + if ip.is_multicast: + return None + if ip.is_global is False: + return None + return (f"Use IPv6 reserved for Documentation (RFC 3849) or private Space: {ip}", cnt, 'error') + + +def lint_AS(cnt, line): + number = re.search(NUMBER, line, re.I) + if number: + pass + # find a way to detect AS numbers + + +def lint_linelen(cnt, line): + line = line.rstrip() + if len(line) > 80: + return (f"Line too long: len={len(line)}", cnt, 'warning') + +def handle_file_action(filepath): + errors = [] + try: + with open(filepath) as fp: + line = fp.readline() + cnt = 1 + test_line_lenght = True + start_vyoslinter = True + indentation = 0 + while line: + # search for ignore linter comments in lines + if ".. stop_vyoslinter" in line: + start_vyoslinter = False + if ".. start_vyoslinter" in line: + start_vyoslinter = True + if start_vyoslinter: + # ignore every '.. code-block::' for line lenght + # rst code-block have its own style in html the format in rst + # and the build page must be the same + if test_line_lenght is False: + if len(line) > indentation: + #print(f"'{line}'") + #print(indentation) + if line[indentation].isspace() is False: + test_line_lenght = True + + if ".. code-block::" in line: + test_line_lenght = False + indentation = 0 + for i in line: + if i.isspace(): + indentation = indentation + 1 + else: + break + + err_mac = lint_mac(cnt, line.strip()) + # disable mac detection for the moment, too many false positives + err_mac = None + err_ip4 = lint_ipv4(cnt, line.strip()) + err_ip6 = lint_ipv6(cnt, line.strip()) + if test_line_lenght: + err_len = lint_linelen(cnt, line) + else: + err_len = None + if err_mac: + errors.append(err_mac) + if err_ip4: + errors.append(err_ip4) + if err_ip6: + errors.append(err_ip6) + if err_len: + errors.append(err_len) + + line = fp.readline() + cnt += 1 + + # ensure linter was not stop on top and forgot to tun on again + if start_vyoslinter == False: + errors.append((f"Don't forgett to turn linter back on", cnt, 'error')) + finally: + fp.close() + + if len(errors) > 0: + ''' + "::{$type} file={$filename},line={$line},col=$column::{$log}" + ''' + print(f"File: {filepath}") + for error in errors: + print(f"::{error[2]} file={filepath},line={error[1]}::{error[0]}") + print('') + return False + + +def main(): + bool_error = True + print('start') + try: + files = ast.literal_eval(sys.argv[1]) + for file in files: + if file[-4:] in [".rst", ".txt"] and "_build" not in file: + if handle_file_action(file) is False: + bool_error = False + except Exception as e: + for root, dirs, files in os.walk("docs"): + path = root.split(os.sep) + for file in files: + if file[-4:] in [".rst", ".txt"] and "_build" not in path: + fpath = '/'.join(path) + filepath = f"{fpath}/{file}" + if handle_file_action(filepath) is False: + bool_error = False + + return bool_error + + +if __name__ == "__main__": + if main() == False: + exit(1) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000..eb04d97f --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,32 @@ +name: Linting +on: + pull_request: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: File Changes + id: file_changes + uses: trilom/file-changes-action@v1.2.3 + + #- name: Vale + # uses: errata-ai/vale-action@v1.3.0 + # with: + # files: '${{ steps.file_changes.outputs.files_modified }}' + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: run python based linter + run: python .github/vyos-linter.py '${{ steps.file_changes.outputs.files_modified }}' + + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + + diff --git a/.github/workflows/submodules.yml b/.github/workflows/submodules.yml new file mode 100644 index 00000000..82b8d4e4 --- /dev/null +++ b/.github/workflows/submodules.yml @@ -0,0 +1,62 @@ +name: Update submodule vyos-1x +on: + workflow_dispatch: + schedule: + # 06:00 UTC on Monday + - cron: '0 6 * * 1' +jobs: + updateVyOS-1x_master: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + repository: ${{ github.repository }} + - name: update submodule + run: | + git submodule status + git submodule update --init --force + cd docs/_include/vyos-1x + git checkout current + git pull + git submodule status + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + token: ${{secrets.GITHUB_TOKEN}} + commit-message: "vyos-1x: update current branch" + committer: GitHub <noreply@github.com> + author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> + title: "vyos-1x: update current branch" + body: | + Autoupdate vyos-1x submodule + branch: update-dependencies-master + delete-branch: true + + + updateVyOS-1x_equuleus: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + repository: ${{ github.repository }} + ref: equuleus + - name: update submodule + run: | + git submodule status + git submodule update --init --force + cd docs/_include/vyos-1x + git checkout equuleus + git pull + git submodule status + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + token: ${{secrets.GITHUB_TOKEN}} + commit-message: "vyos-1x: update equuleus branch" + committer: GitHub <noreply@github.com> + author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> + title: "vyos-1x: update equuleus branch" + body: | + Autoupdate vyos-1x submodule + branch: update-dependencies-equuleus + delete-branch: true @@ -1,3 +1,6 @@ +# Sphinx +_build/ + # python virtualenv venv/ ENV/ @@ -12,7 +15,7 @@ ENV/ # python cache files *.pyc -__pychache__ +__pycache__ # dotenv .env 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/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..56ce79a7 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,27 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Build documentation with MkDocs +#mkdocs: +# configuration: mkdocs.yml + +# Optionally build your docs in additional formats such as PDF +formats: + - pdf + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: requirements.txt + +submodules: + include: all
\ No newline at end of file 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" @@ -1,17 +1,38 @@ -Starting with VyOS 1.2 (`crux`) documentation will be migrated from the old wiki -to ReadTheDocs. Documentation can be accessed via the following URL: +Starting with VyOS 1.2 (`crux`) our documentation is being migrated from the old wiki +to ReadTheDocs. Documentation can be accessed via the following URL: https://docs.vyos.io -* https://docs.vyos.io +Our old WiKi can still be accessed from the +[Wayback Machine](https://web.archive.org/web/20200225171529/https://wiki.vyos.net/wiki/Main_Page) # Build [](https://docs.vyos.io/en/latest/?badge=latest) +# Versions + +Our version follows the very same branching scheme as the VyOS source modules +itself. We maintain one documentation branch per VyOS release. The default +branch that contains the most recent VyOS documentation is called `master` +and matches the latest VyOS release which is 1.4 at the time. + +All new documentation enhancements go to the `master` branch. If those changes +are beneficial for previous VyOS documentation versions they will be +cherry-picked to the appropriate branch(es). + +Post-1.2.0 branches are named after constellations sorted by area from smallest to +largest. There are 88 of them, here's the +[complete list](https://en.wikipedia.org/wiki/IAU_designated_constellations_by_area). + +* 1.2.x: `crux` (Southern Cross) +* 1.3.x: `equuleus` (Little Horse) +* 1.4.x: `sagitta` (Arrow) +* ... + ## Native -To build the manual run the following commands inside the `docs` folder: +To build the manual, run the following commands inside the `docs` folder: -* `make html` for a HTML manual +* `make html` for an HTML manual * `make latexpdf` for a LaTeX rendered PDF Required Debian Packages: @@ -22,28 +43,28 @@ Required Debian Packages: * `sphinx` ### sphinx -Debian, requires some extra steps for +Debian requires some extra steps for installing `sphinx`, `sphinx-autobuild` and `sphinx-rtd-theme` packages: -First ensure that phython2 & phython3 are installed and phython3 is the default: +First ensure that Python 2 & Python 3 are installed and Python 3 is the default: ```bash python --version ``` -Alternatively, to make python3 the default, revise the following line to -point to the relevant 3.x version of the binary on your system: +Alternatively, to make Python the default, revise the following line to +point at the relevant 3.x version of the binary on your system: ```bash sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 0 ``` -Then follow these steps to install sphinx group of packages: +Then install the sphinx group of packages: ```bash sudo apt-get install python3-sphinx ``` -Although mostly everything uses phython3, But to install this specific -package, make sure that pip points to the python2 version of the package manager: +Although almost everything uses Python 3, in order to install this specific +package, make sure that pip points at the Python 2 version of the package manager: ```bash python --version @@ -56,29 +77,29 @@ sudo pip install sphinx-rtd-theme ``` -Do the following to build the html and start a webeserver: +Do the following to build the HTML and start a webserver: * Run `make livehtml` inside the `docs` folder Then, to view the live output: * Browse to http://localhost:8000 -Note: The changes you save to the sources are represented in the live HTML outout +Note: The changes you save to the sources are represented in the live HTML output automatically (and almost instantly) without the need to rebuild or refresh manually. ## Docker -Using our [Dockerfile](docker/Dockerfile) you create your own Docker container +Using our [Dockerfile](docker/Dockerfile) you can create your own Docker container that is used to build a VyOS documentation. ## Setup -You can either build the container on your own or directly fetch it prebuild +You can either build the container on your own or directly fetch it prebuilt from Dockerhub. If you want to build it for yourself, use the following command. ```bash $ docker build -t vyos/vyos-documentation docker ``` -### Build documentation +### Building documentation If the `vyos/vyos-documentation` container could not be found locally it will be automatically fetched from Dockerhub. @@ -103,7 +124,7 @@ $ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \ -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale . ``` -to test a specific file e.g. `clustering.rst` +to test a specific file (e.g. `clustering.rst`) ```bash $ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) \ diff --git a/ci/vyos-linter.py b/ci/vyos-linter.py deleted file mode 100644 index 3bf65484..00000000 --- a/ci/vyos-linter.py +++ /dev/null @@ -1,117 +0,0 @@ -import os -import re -import ipaddress - -IPV4SEG = r'(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])' -IPV4ADDR = r'(?:(?:' + IPV4SEG + r'\.){3,3}' + IPV4SEG + r')' -IPV6SEG = r'(?:(?:[0-9a-fA-F]){1,4})' -IPV6GROUPS = ( - r'(?:' + IPV6SEG + r':){7,7}' + IPV6SEG, # 1:2:3:4:5:6:7:8 - r'(?:\s' + IPV6SEG + r':){1,7}:', # 1:: 1:2:3:4:5:6:7:: - r'(?:' + IPV6SEG + r':){1,6}:' + IPV6SEG, # 1::8 1:2:3:4:5:6::8 1:2:3:4:5:6::8 - r'(?:' + IPV6SEG + r':){1,5}(?::' + IPV6SEG + r'){1,2}', # 1::7:8 1:2:3:4:5::7:8 1:2:3:4:5::8 - r'(?:' + IPV6SEG + r':){1,4}(?::' + IPV6SEG + r'){1,3}', # 1::6:7:8 1:2:3:4::6:7:8 1:2:3:4::8 - r'(?:' + IPV6SEG + r':){1,3}(?::' + IPV6SEG + r'){1,4}', # 1::5:6:7:8 1:2:3::5:6:7:8 1:2:3::8 - r'(?:' + IPV6SEG + r':){1,2}(?::' + IPV6SEG + r'){1,5}', # 1::4:5:6:7:8 1:2::4:5:6:7:8 1:2::8 - IPV6SEG + r':(?:(?::' + IPV6SEG + r'){1,6})', # 1::3:4:5:6:7:8 1::3:4:5:6:7:8 1::8 - r':(?:(?::' + IPV6SEG + r'){1,7}|:)', # ::2:3:4:5:6:7:8 ::2:3:4:5:6:7:8 ::8 :: - r'fe80:(?::' + IPV6SEG + r'){0,4}%[0-9a-zA-Z]{1,}', # fe80::7:8%eth0 fe80::7:8%1 (link-local IPv6 addresses with zone index) - r'::(?:ffff(?::0{1,4}){0,1}:){0,1}[^\s:]' + IPV4ADDR, # ::255.255.255.255 ::ffff:255.255.255.255 ::ffff:0:255.255.255.255 (IPv4-mapped IPv6 addresses and IPv4-translated addresses) - r'(?:' + IPV6SEG + r':){1,4}:[^\s:]' + IPV4ADDR, # 2001:db8:3:4::192.0.2.33 64:ff9b::192.0.2.33 (IPv4-Embedded IPv6 Address) -) -IPV6ADDR = '|'.join(['(?:{})'.format(g) for g in IPV6GROUPS[::-1]]) # Reverse rows for greedy match - -MAC = r'([0-9A-F]{2}[:-]){5}([0-9A-F]{2})' - -NUMBER = r"([\s']\d+[\s'])" - - -def lint_mac(cnt, line): - mac = re.search(MAC, line, re.I) - if mac is not None: - mac = mac.group() - u_mac = re.search(r'((00)[:-](53)([:-][0-9A-F]{2}){4})', mac, re.I) - m_mac = re.search(r'((90)[:-](10)([:-][0-9A-F]{2}){4})', mac, re.I) - if u_mac is None and m_mac is None: - return f"MAC-Address Error Line {cnt}: {mac}" - - -def lint_ipv4(cnt, line): - ip = re.search(IPV4ADDR, line, re.I) - if ip is not None: - ip = ipaddress.ip_address(ip.group().strip(' ')) - # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_private - if ip.is_private is False and ip.is_multicast is False: - return f"IPv4 Error Line {cnt}: {ip}" - - -def lint_ipv6(cnt, line): - ip = re.search(IPV6ADDR, line, re.I) - if ip is not None: - ip = ipaddress.ip_address(ip.group().strip(' ')) - # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_private - if ip.is_private is False and ip.is_multicast is False: - return f"IPv6 Error Line {cnt}: {ip}" - - -def lint_AS(cnt, line): - number = re.search(NUMBER, line, re.I) - if number: - pass - # find a way to detect AS numbers - - -def lint_linelen(cnt, line): - if len(line) > 80: - return f"Line {cnt} too long: len={len(line)}" - - -def handle_file(path, file): - errors = [] - path = '/'.join(path) - filepath = f"{path}/{file}" - try: - with open(filepath) as fp: - line = fp.readline() - cnt = 1 - while line: - err_mac = lint_mac(cnt, line.strip()) - err_ip4 = lint_ipv4(cnt, line.strip()) - err_ip6 = lint_ipv6(cnt, line.strip()) - err_len = lint_linelen(cnt, line.strip()) - if err_mac: - errors.append(err_mac) - if err_ip4: - errors.append(err_ip4) - if err_ip6: - errors.append(err_ip6) - if err_len: - errors.append(err_len) - line = fp.readline() - cnt += 1 - finally: - fp.close() - - if len(errors) > 0: - print(f"File: {filepath}") - for error in errors: - print(error) - print('') - return False - - -def main(): - bool_error = True - # TODO: path and/or files via cli arg - for root, dirs, files in os.walk("../docs"): - path = root.split(os.sep) - for file in files: - if file[-4:] == ".rst": - if handle_file(path, file) is False: - bool_error = False - return bool_error - - -if __name__ == "__main__": - if main() is False: - exit(1) diff --git a/docker/Dockerfile b/docker/Dockerfile index 02b0fc26..903a8e83 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -33,6 +33,7 @@ RUN pip3 install Sphinx RUN pip3 install sphinx-rtd-theme RUN pip3 install sphinx-autobuild RUN pip3 install sphinx-notfound-page +RUN pip3 install lxml # Cleanup 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/Makefile b/docs/Makefile index 5d4864e1..7bc0c5ab 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,9 +8,9 @@ SPHINXPROJ = VyOS SOURCEDIR = . BUILDDIR = _build -AUTOHOST =0.0.0.0 -AUTOPORT =8000 -AUTOOPTS =--poll +AUTOHOST = 0.0.0.0 +AUTOPORT = 8000 +AUTOOPTS = --watch . # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/_ext/testcoverage.py b/docs/_ext/testcoverage.py new file mode 100644 index 00000000..39028912 --- /dev/null +++ b/docs/_ext/testcoverage.py @@ -0,0 +1,382 @@ +''' +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 <include" in line.strip(): + include_filename = line.strip().split('<')[1][:-1] + with open(input_dir + include_filename) as ifp: + iline = ifp.readline() + while iline: + string = string + include_file(iline.strip(), input_dir) + iline = ifp.readline() + else: + string = line + return string + + +def get_working_commands(): + for entry in input_data: + for (dirpath, dirnames, filenames) in os.walk(entry['input_dir']): + entry['files'].extend(filenames) + break + + for f in entry['files']: + + string = "" + with open(entry['input_dir'] + f) as fp: + line = fp.readline() + while line: + string = string + include_file(line.strip(), entry['input_dir']) + line = fp.readline() + + try: + xml = ET.parse(BytesIO(bytes(string, 'utf-8'))) + except Exception as e: + print("Failed to load interface definition file {0}".format(f)) + print(e) + sys.exit(1) + + override_defaults(xml) + + try: + relaxng_xml = ET.parse(entry['schema_file']) + validator = ET.RelaxNG(relaxng_xml) + + if not validator.validate(xml): + print(validator.error_log) + print("Interface definition file {0} does not match the schema!".format(f)) + sys.exit(1) + except Exception as e: + print("Failed to load the XML schema {0}".format(entry['schema_file'])) + print(e) + sys.exit(1) + + root = xml.getroot() + nodes = root.iterfind("*") + for n in nodes: + node_data[entry['kind']][f] = process_node(n, f) + + # build config tree and sort + + config_tree_new = { + 'cfgcmd': {}, + 'opcmd': {}, + } + + for kind in node_data: + for entry in node_data[kind]: + node_0 = node_data[kind][entry]['name'] + + if node_0 not in config_tree_new[kind].keys(): + config_tree_new[kind][node_0] = { + 'name': node_0, + 'type': node_data[kind][entry]['type'], + 'props': node_data[kind][entry]['props'], + 'children': [], + 'command': node_data[kind][entry]['command'], + 'filename': node_data[kind][entry]['filename'], + } + config_tree_new[kind][node_0]['children'].extend(node_data[kind][entry]['children']) + + result = { + 'cfgcmd': [], + 'opcmd': [], + } + for kind in config_tree_new: + for e in config_tree_new[kind]: + result[kind].extend(create_commands(config_tree_new[kind][e])) + + for cmd in result['cfgcmd']: + cmd['cmd'] = " ".join(cmd['name']) + for cmd in result['opcmd']: + cmd['cmd'] = " ".join(cmd['name']) + return result + +def override_defaults(xml): + root = xml.getroot() + defv = {} + + xpath_str = f'//defaultValue' + xp = xml.xpath(xpath_str) + + for element in xp: + ap = element.xpath('ancestor::*[@name]') + defv.setdefault((ap[-1].get("name"), str(ap[:-1])), []).append(element) + + for k, v in defv.items(): + if len(v) > 1: + override_element(v) + +def override_element(l: list): + if len(l) < 2: + return + + # assemble list of leafNodes of overriding defaultValues, for later removal + parents = [] + for el in l[1:]: + parents.append(el.getparent()) + + # replace element with final override + l[0].getparent().replace(l[0], l[-1]) + + # remove all but overridden element + for el in parents: + el.getparent().remove(el) + +if __name__ == "__main__": + res = get_working_commands() + print(json.dumps(res)) + #print(res['cfgcmd'][0]) diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 4ee87d63..46ebae36 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -1,21 +1,42 @@ -from docutils import nodes, utils +import re +import json +import os +from docutils import io, nodes, utils, statemachine from docutils.parsers.rst.roles import set_classes -from docutils.parsers.rst import Directive +from docutils.parsers.rst import Directive, directives, states + from sphinx.util.docutils import SphinxDirective +from testcoverage import get_working_commands + def setup(app): app.add_config_value( 'vyos_phabricator_url', - 'https://phabricator.vyos.net/', '' + 'https://phabricator.vyos.net/', + 'html' + ) + + app.add_config_value( + 'vyos_working_commands', + get_working_commands(), + #{"cfgcmd": [], "opcmd": []}, + 'html' + ) + app.add_config_value( + 'vyos_coverage', + { + 'cfgcmd': [0,len(app.config.vyos_working_commands['cfgcmd'])], + 'opcmd': [0,len(app.config.vyos_working_commands['opcmd'])] + }, + 'html' ) + app.add_role('vytask', vytask_role) app.add_role('cfgcmd', cmd_role) app.add_role('opcmd', cmd_role) - print(app.config.vyos_phabricator_url) - app.add_node( inlinecmd, html=(inlinecmd.visit_span, inlinecmd.depart_span), @@ -42,24 +63,29 @@ def setup(app): text=(CmdHeader.visit_div, CmdHeader.depart_div) ) app.add_node(CfgcmdList) + app.add_node(CfgcmdListCoverage) app.add_directive('cfgcmdlist', CfgcmdlistDirective) app.add_node(OpcmdList) + app.add_node(OpcmdListCoverage) app.add_directive('opcmdlist', OpcmdlistDirective) app.add_directive('cfgcmd', CfgCmdDirective) app.add_directive('opcmd', OpCmdDirective) + app.add_directive('cmdinclude', CfgInclude) app.connect('doctree-resolved', process_cmd_nodes) - class CfgcmdList(nodes.General, nodes.Element): pass - class OpcmdList(nodes.General, nodes.Element): pass -import json +class CfgcmdListCoverage(nodes.General, nodes.Element): + pass + +class OpcmdListCoverage(nodes.General, nodes.Element): + pass class CmdHeader(nodes.General, nodes.Element): @@ -148,16 +174,177 @@ class inlinecmd(nodes.inline): #self.literal_whitespace -= 1 +class CfgInclude(SphinxDirective): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'var0': str, + 'var1': str, + 'var2': str, + 'var3': str, + 'var4': str, + 'var5': str, + 'var6': str, + 'var7': str, + 'var8': str, + 'var9': str + } + standard_include_path = os.path.join(os.path.dirname(states.__file__), + 'include') + + def run(self): + ### Copy from include directive docutils + """Include a file as part of the content of this reST file.""" + rel_filename, filename = self.env.relfn2path(self.arguments[0]) + self.arguments[0] = filename + self.env.note_included(filename) + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = directives.path(self.arguments[0]) + if path.startswith('<') and path.endswith('>'): + path = os.path.join(self.standard_include_path, path[1:-1]) + path = os.path.normpath(os.path.join(source_dir, path)) + path = utils.relative_path(None, path) + path = nodes.reprunicode(path) + encoding = self.options.get( + 'encoding', self.state.document.settings.input_encoding) + e_handler=self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get( + 'tab-width', self.state.document.settings.tab_width) + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError: + raise self.severe(u'Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError as error: + raise self.severe(u'Problems with "%s" directive path:\n%s.' % + (self.name, error)) + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = ''.join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError: + raise self.severe(u'Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get('start-after', None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[after_index + len(after_text):] + before_text = self.options.get('end-before', None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[:before_index] + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + if 'literal' in self.options: + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get('class', [])) + literal_block.line = 1 + self.add_name(literal_block) + if 'number-lines' in self.options: + try: + startline = int(self.options['number-lines'] or 1) + except ValueError: + raise self.error(':number-lines: with non-integer ' + 'start value') + endline = startline + len(include_lines) + if text.endswith('\n'): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + if 'code' in self.options: + self.options['source'] = path + codeblock = CodeBlock(self.name, + [self.options.pop('code')], # arguments + self.options, + include_lines, # content + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + + new_include_lines = [] + for line in include_lines: + for i in range(10): + value = self.options.get(f'var{i}','') + if value == '': + line = re.sub('\s?{{\s?var' + str(i) + '\s?}}',value,line) + else: + line = re.sub('{{\s?var' + str(i) + '\s?}}',value,line) + new_include_lines.append(line) + self.state_machine.insert_input(new_include_lines, path) + return [] + + class CfgcmdlistDirective(Directive): + has_content = False + required_arguments = 0 + option_spec = { + 'show-coverage': directives.flag + } def run(self): - return [CfgcmdList('')] + cfglist = CfgcmdList() + cfglist['coverage'] = False + if 'show-coverage' in self.options: + cfglist['coverage'] = True + return [cfglist] class OpcmdlistDirective(Directive): + has_content = False + required_arguments = 0 + option_spec = { + 'show-coverage': directives.flag + } def run(self): - return [OpcmdList('')] + oplist = OpcmdList() + oplist['coverage'] = False + if 'show-coverage' in self.options: + oplist['coverage'] = True + + return [oplist] + class CmdDirective(SphinxDirective): @@ -165,7 +352,8 @@ class CmdDirective(SphinxDirective): has_content = True custom_class = '' - def run(self): + def run(self): + title_list = [] content_list = [] title_text = '' @@ -243,7 +431,148 @@ class CfgCmdDirective(CmdDirective): custom_class = 'cfg' -def process_cmd_node(app, cmd, fromdocname): +def strip_cmd(cmd, debug=False): + if debug: + print("") + print(cmd) + cmd = re.sub('set','',cmd) + if debug: + print(cmd) + #while " | " in cmd: + cmd = re.sub('\s+\|\s+','',cmd) + if debug: + print(cmd) + cmd = re.sub('<\S*>','',cmd) + if debug: + print(cmd) + cmd = re.sub('\[\S\]','',cmd) + if debug: + print(cmd) + cmd = re.sub('\s+','',cmd) + if debug: + print(cmd) + print("") + 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) + + + #print(coverage_list.keys()) + + 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: + 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'] @@ -258,21 +587,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 = [] - - for cmd in sorted(env.vyos_opcmd, key=lambda i: i['cmd']): - content.append(process_cmd_node(app, cmd, fromdocname)) - node.replace_self(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) + + except Exception as inst: + print(inst) def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): @@ -287,4 +640,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/common-references.rst b/docs/_include/common-references.txt index d7e376eb..de4f76e7 100644 --- a/docs/common-references.rst +++ b/docs/_include/common-references.txt @@ -1,3 +1,9 @@ +.. stop_vyoslinter + .. _`accel-ppp`: https://accel-ppp.org/ .. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol .. _Phabricator: https://phabricator.vyos.net/ +.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad +.. _802.1q: https://en.wikipedia.org/wiki/IEEE_802.1Q + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/draw.io/pbr_example_1.drawio b/docs/_include/draw.io/pbr_example_1.drawio index 0d496572..0d496572 100644 --- a/docs/draw.io/pbr_example_1.drawio +++ b/docs/_include/draw.io/pbr_example_1.drawio diff --git a/docs/draw.io/vpn_s2s_ikev2.drawio b/docs/_include/draw.io/vpn_s2s_ikev2.drawio index b240c191..b240c191 100644 --- a/docs/draw.io/vpn_s2s_ikev2.drawio +++ b/docs/_include/draw.io/vpn_s2s_ikev2.drawio diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt new file mode 100644 index 00000000..4ff78c01 --- /dev/null +++ b/docs/_include/interface-address-with-dhcp.txt @@ -0,0 +1,21 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} address 2001:db8::1/64 + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6
\ No newline at end of file diff --git a/docs/_include/interface-address.txt b/docs/_include/interface-address.txt new file mode 100644 index 00000000..00a9ec09 --- /dev/null +++ b/docs/_include/interface-address.txt @@ -0,0 +1,14 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::1/64
\ No newline at end of file diff --git a/docs/_include/interface-common-with-dhcp.txt b/docs/_include/interface-common-with-dhcp.txt new file mode 100644 index 00000000..47b4796f --- /dev/null +++ b/docs/_include/interface-common-with-dhcp.txt @@ -0,0 +1,21 @@ +.. cmdinclude:: /_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-common.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +**DHCP(v6)** + +.. cmdinclude:: /_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-dhcpv6-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: {{ var0 }} + :var1: {{ var1 }} diff --git a/docs/_include/interface-common-without-dhcp.txt b/docs/_include/interface-common-without-dhcp.txt new file mode 100644 index 00000000..73d39dd0 --- /dev/null +++ b/docs/_include/interface-common-without-dhcp.txt @@ -0,0 +1,7 @@ +.. cmdinclude:: /_include/interface-address.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-common.txt + :var0: {{ var0 }} + :var1: {{ var1 }} diff --git a/docs/_include/interface-common.txt b/docs/_include/interface-common.txt new file mode 100644 index 00000000..5a997482 --- /dev/null +++ b/docs/_include/interface-common.txt @@ -0,0 +1,35 @@ +.. cmdinclude:: /_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-disable-flow-control.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-ip.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt new file mode 100644 index 00000000..064d9559 --- /dev/null +++ b/docs/_include/interface-description.txt @@ -0,0 +1,11 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} description <description> + + Set a human readable, descriptive alias for this connection. Alias is used by + e.g. the :opcmd:`show interfaces` command or SNMP based monitoring tools. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} description 'This is an awesome interface running on VyOS'
\ No newline at end of file diff --git a/docs/_include/interface-dhcp-options.txt b/docs/_include/interface-dhcp-options.txt new file mode 100644 index 00000000..1a0ce260 --- /dev/null +++ b/docs/_include/interface-dhcp-options.txt @@ -0,0 +1,50 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcp-options client-id <description> + + :rfc:`2131` states: The client MAY choose to explicitly provide the identifier + through the 'client identifier' option. If the client supplies a 'client + identifier', the client MUST use the same 'client identifier' in all + subsequent messages, and the server MUST use that identifier to identify the + client. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options client-id 'foo-bar' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcp-options host-name <hostname> + + Instead of sending the real system hostname to the DHCP server, overwrite the + host-name with this given-value. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options host-name 'VyOS' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcp-options vendor-class-id <vendor-id> + + The vendor-class-id option can be used to request a specific class of vendor + options from the server. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options vendor-class-id 'VyOS' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcp-options no-default-route + + Only request an address from the DHCP server but do not request a default + gateway. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcp-options no-default-route diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt new file mode 100644 index 00000000..e047e92a --- /dev/null +++ b/docs/_include/interface-dhcpv6-options.txt @@ -0,0 +1,44 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options duid <duid> + + The DHCP unique identifier (DUID) is used by a client to get an IP address + from a DHCPv6 server. It has a 2-byte DUID type field, and a variable-length + identifier field up to 128 bytes. Its actual length depends on its type. The + server compares the DUID with its database and delivers configuration data + (address, lease times, DNS servers, etc.) to the client. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} duid '0e:00:00:01:00:01:27:71:db:f0:00:50:56:bf:c5:6d' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options parameters-only + + This statement specifies dhcp6c to only exchange informational configuration + parameters with servers. A list of DNS server addresses is an example of such + parameters. This statement is useful when the client does not need stateful + configuration parameters such as IPv6 addresses or prefixes. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options parameters-only + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options rapid-commit + + When rapid-commit is specified, dhcp6c will include a rapid-commit option in + solicit messages and wait for an immediate reply instead of advertisements. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options rapid-commit + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options temporary + + Request only a temporary address and not form an IA_NA (Identity Association + for Non-temporary Addresses) partnership. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options temporary diff --git a/docs/_include/interface-dhcpv6-prefix-delegation.txt b/docs/_include/interface-dhcpv6-prefix-delegation.txt new file mode 100644 index 00000000..1ef94c14 --- /dev/null +++ b/docs/_include/interface-dhcpv6-prefix-delegation.txt @@ -0,0 +1,62 @@ +**DHCPv6 Prefix Delegation (PD)** + +VyOS 1.3 (equuleus) supports DHCPv6-PD (:rfc:`3633`). DHCPv6 Prefix Delegation +is supported by most ISPs who provide native IPv6 for consumers on fixed +networks. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> length <length> + + Some ISPs by default only delegate a /64 prefix. To request for a specific + prefix size use this option to request for a bigger delegation for this pd + `<id>`. This value is in the range from 32 - 64 so you could request up to a + /32 prefix (if your ISP allows this) down to a /64 delegation. + + The default value corresponds to 64. + + To request a /56 prefix from your ISP use: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 length 56 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> interface <delegatee> + address <address> + + Specify the interface address used locally on the interfcae where the prefix + has been delegated to. ID must be a decimal integer. + + It will be combined with the delegated prefix and the sla-id to form a + complete interface address. The default is to use the EUI-64 address of the + interface. + + .. stop_vyoslinter + + Example: Delegate a /64 prefix to interface eth8 which will use a local + address on this router of ``<prefix>::ffff``, as the address 65534 will + correspond to ``ffff`` in hexadecimal notation. + + .. start_vyoslinter + + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 interface eth8 address 65534 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} dhcpv6-options pd <id> interface <delegatee> sla-id <id> + + Specify the identifier value of the site-level aggregator (SLA) on the + interface. ID must be a decimal number greater then 0 which fits in the + length of SLA IDs (see below). + + Example: If ID is 1 and the client is delegated an IPv6 prefix + 2001:db8:ffff::/48, dhcp6c will combine the two values into a single IPv6 + prefix, 2001:db8:ffff:1::/64, and will configure the prefix on the specified + interface. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 interface eth8 sla-id 1 + diff --git a/docs/_include/interface-disable-flow-control.txt b/docs/_include/interface-disable-flow-control.txt new file mode 100644 index 00000000..347f1145 --- /dev/null +++ b/docs/_include/interface-disable-flow-control.txt @@ -0,0 +1,23 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + disable-flow-control + + Ethernet flow control is a mechanism for temporarily stopping the transmission + of data on Ethernet family computer networks. The goal of this mechanism is to + ensure zero packet loss in the presence of network congestion. + + The first flow control mechanism, the pause frame, was defined by the IEEE + 802.3x standard. + + A sending station (computer or network switch) may be transmitting data faster + than the other end of the link can accept it. Using flow control, the + receiving station can signal the sender requesting suspension of + transmissions until the receiver catches up. + + Use this command to disable the generation of Ethernet flow control (pause + frames). + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} disable-flow-control
\ No newline at end of file diff --git a/docs/_include/interface-disable-link-detect.txt b/docs/_include/interface-disable-link-detect.txt new file mode 100644 index 00000000..1a766715 --- /dev/null +++ b/docs/_include/interface-disable-link-detect.txt @@ -0,0 +1,13 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} disable-link-detect + + Use this command to direct an interface to not detect any physical state + changes on a link, for example, when the cable is unplugged. + + Default is to detects physical link state changes. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} disable-link-detect
\ No newline at end of file diff --git a/docs/_include/interface-disable.txt b/docs/_include/interface-disable.txt new file mode 100644 index 00000000..774c1cdd --- /dev/null +++ b/docs/_include/interface-disable.txt @@ -0,0 +1,11 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} disable
\ No newline at end of file diff --git a/docs/_include/interface-eapol.txt b/docs/_include/interface-eapol.txt new file mode 100644 index 00000000..68e5073d --- /dev/null +++ b/docs/_include/interface-eapol.txt @@ -0,0 +1,37 @@ +:abbr:`EAP (Extensible Authentication Protocol)` over LAN (EAPoL) is a network +port authentication protocol used in IEEE 802.1X (Port Based Network Access +Control) developed to give a generic network sign-on to access network +resources. + +EAPoL comes with an identify option. We automatically use the interface MAC +address as identity parameter. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol ca-cert-file <file> + + SSL :abbr:`CA (Certificate Authority)` x509 PEM file used afor authentication + of the remote side. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol ca-cert-file /config/auth/ca.pem + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol cert-file <file> + + SSL/x509 public certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol cert-file /config/auth/public.pem + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol key-file <file> + + SSL/x509 private certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol key-file /config/auth/private.key diff --git a/docs/_include/interface-ip.txt b/docs/_include/interface-ip.txt new file mode 100644 index 00000000..89937806 --- /dev/null +++ b/docs/_include/interface-ip.txt @@ -0,0 +1,157 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip arp-cache-timeout + + Once a neighbor has been found, the entry is considered to be valid for at + least for this specifc time. An entry's validity will be extended if it + receives positive feedback from higher level protocols. + + This defaults to 30 seconds. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip arp-cache-timeout 180 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip disable-arp-filter + + If set the kernel can respond to arp requests with addresses from other + interfaces. This may seem wrong but it usually makes sense, because it + increases the chance of successful communication. IP addresses are owned by + the complete host on Linux, not by particular interfaces. Only for more + complex setups like load-balancing, does this behaviour cause problems. + + If not set (default) allows you to have multiple network interfaces on the + same subnet, and have the ARPs for each interface be answered based on whether + or not the kernel would route a packet from the ARP'd IP out that interface + (therefore you must use source based routing for this to work). + + In other words it allows control of which cards (usually 1) will respond to an + arp request. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-arp-filter + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-forwarding + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip enable-arp-accept + + Define behavior for gratuitous ARP frames who's IP is not already present in + the ARP table. If configured create new entries in the ARP table. + + Both replies and requests type gratuitous arp will trigger the ARP table to be + updated, if this setting is on. + + If the ARP table already contains the IP address of the gratuitous arp frame, + the arp table will be updated regardless if this setting is on or off. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-accept + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip enable-arp-announce + + Define different restriction levels for announcing the local source IP address + from IP packets in ARP requests sent on interface. + + Use any local address, configured on any interface if this is not set. + + If configured, try to avoid local addresses that are not in the target's + subnet for this interface. This mode is useful when target hosts reachable via + this interface require the source IP address in ARP requests to be part of + their logical network configured on the receiving interface. When we generate + the request we will check all our subnets that include the target IP and will + preserve the source address if it is from such subnet. If there is no such + subnet we select source address according to the rules for level 2. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-announce + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip enable-arp-ignore + + Define different modes for sending replies in response to received ARP + requests that resolve local target IP addresses: + + If configured, reply only if the target IP address is local address configured + on the incoming interface. + + If this option is unset (default), reply for any local target IP address, + configured on any interface. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-ignore + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip enable-proxy-arp + + Use this command to enable proxy Address Resolution Protocol (ARP) on this + interface. Proxy ARP allows an Ethernet interface to respond with its own + :abbr:`MAC (Media Access Control)` address to ARP requests for destination IP + addresses on subnets attached to other interfaces on the system. Subsequent + packets sent to those destination IP addresses are forwarded appropriately by + the system. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-proxy-arp + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip proxy-arp-pvlan + + Private VLAN proxy arp. Basically allow proxy arp replies back to the same + interface (from which the ARP request/solicitation was received). + + This is done to support (ethernet) switch features, like :rfc:`3069`, where + the individual ports are NOT allowed to communicate with each other, but they + are allowed to talk to the upstream router. As described in :rfc:`3069`, it is + possible to allow these hosts to communicate through the upstream router by + proxy_arp'ing. + + .. note:: Don't need to be used together with proxy_arp. + + This technology is known by different names: + + - In :rfc:`3069` it is called VLAN Aggregation + + - Cisco and Allied Telesyn call it Private VLAN + + - Hewlett-Packard call it Source-Port filtering or port-isolation + + - Ericsson call it MAC-Forced Forwarding (RFC Draft) + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ip source-validation <strict | loose | disable> + + Enable policy for source validation by reversed path, as specified in + :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict + mode to prevent IP spoofing from DDos attacks. If using asymmetric routing + or other complicated routing, then loose mode is recommended. + + - strict: Each incoming packet is tested against the FIB and if the interface + is not the best reverse path the packet check will fail. By default failed + packets are discarded. + + - loose: Each incoming packet's source address is also tested against the FIB + and if the source address is not reachable via any interface the packet + check will fail. + + - disable: No source validation diff --git a/docs/_include/interface-ipv6.txt b/docs/_include/interface-ipv6.txt new file mode 100644 index 00000000..e03817cf --- /dev/null +++ b/docs/_include/interface-ipv6.txt @@ -0,0 +1,55 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ipv6 address autoconf + + :abbr:`SLAAC (Stateless Address Autoconfiguration)` :rfc:`4862`. IPv6 hosts + can configure themselves automatically when connected to an IPv6 network using + the Neighbor Discovery Protocol via :abbr:`ICMPv6 (Internet Control Message + Protocol version 6)` router discovery messages. When first connected to a + network, a host sends a link-local router solicitation multicast request for + its configuration parameters; routers respond to such a request with a router + advertisement packet that contains Internet Layer configuration parameters. + + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address autoconf + + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address eui64 2001:db8:beef::/64 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ipv6 address no-default-link-local + + Do not assign a link-local IPv6 address to this interface. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 address no-default-link-local + +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} ipv6 disable-forwarding + + Configure interface-specific Host/Router behaviour. If set, the interface will + switch to host mode and IPv6 forwarding will be disabled on this interface. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 disable-forwarding diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt new file mode 100644 index 00000000..03aa6106 --- /dev/null +++ b/docs/_include/interface-mac.txt @@ -0,0 +1,11 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} mac <xx:xx:xx:xx:xx:xx> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mac '00:01:02:03:04:05'
\ No newline at end of file diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt new file mode 100644 index 00000000..f2b340fe --- /dev/null +++ b/docs/_include/interface-mirror.txt @@ -0,0 +1,34 @@ +SPAN port mirroring can copy the inbound/outbound traffic of the interface to +the specified interface, usually the interface can be connected to some special +equipment, such as behavior control system, intrusion detection system and +traffic collector, and can copy all related traffic from this port + +VyOS uses the `mirror` option to configure port mirroring. The configuration +is divided into 2 different directions. Destination ports should be configured +for different traffic directions. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> mirror + ingress <monitor-interface> + + Configure port mirroring for `interface` inbound traffic and copy the + traffic to `monitor-interface` + + Example: Mirror the inbound traffic of `{{ var1 }}` port to `{{ var2 }}` + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mirror ingress {{ var2 }} + +.. cfgcmd:: set interfaces {{ var0 }} <interface> mirror egress + <monitor-interface> + + Configure port mirroring for `interface` outbound traffic and copy the + traffic to `monitor-interface` + + Example: Mirror the outbound traffic of `{{ var1 }}` port to `{{ var2 }}` + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mirror egress {{ var2 }} + + diff --git a/docs/_include/interface-mtu.txt b/docs/_include/interface-mtu.txt new file mode 100644 index 00000000..76812507 --- /dev/null +++ b/docs/_include/interface-mtu.txt @@ -0,0 +1,11 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} mtu 9000
\ No newline at end of file diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt new file mode 100644 index 00000000..0a1722dc --- /dev/null +++ b/docs/_include/interface-vlan-8021ad.txt @@ -0,0 +1,153 @@ +.. include:: /_include/need_improvement.txt + +IEEE 802.1ad_ was an Ethernet networking standard informally known as QinQ as +an amendment to IEEE standard 802.1q VLAN interfaces as described above. +802.1ad was incorporated into the base 802.1q_ standard in 2011. The technique +is also known as provider bridging, Stacked VLANs, or simply QinQ or Q-in-Q. +"Q-in-Q" can for supported devices apply to C-tag stacking on C-tag (Ethernet +Type = 0x8100). + +The original 802.1q_ specification allows a single Virtual Local Area Network +(VLAN) header to be inserted into an Ethernet frame. QinQ allows multiple +VLAN tags to be inserted into a single frame, an essential capability for +implementing Metro Ethernet network topologies. Just as QinQ extends 802.1Q, +QinQ itself is extended by other Metro Ethernet protocols. + +In a multiple VLAN header context, out of convenience the term "VLAN tag" or +just "tag" for short is often used in place of "802.1q_ VLAN header". QinQ +allows multiple VLAN tags in an Ethernet frame; together these tags constitute +a tag stack. When used in the context of an Ethernet frame, a QinQ frame is a +frame that has 2 VLAN 802.1q_ headers (double-tagged). + +In VyOS the terms ``vif-s`` and ``vif-c`` stand for the ethertype tags that +are used. + +The inner tag is the tag which is closest to the payload portion of the frame. +It is officially called C-TAG (customer tag, with ethertype 0x8100). The outer +tag is the one closer/closest to the Ethernet header, its name is S-TAG +(service tag with Ethernet Type = 0x88a8). + + +.. cmdinclude:: /_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-ip.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +**DHCP(v6)** + +.. cmdinclude:: /_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-dhcpv6-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif-s + :var3: <vlan-id> + :var4: 1000 + :var5: vif-c + :var6: <vlan-id> + :var7: 20 + +.. include:: /_include/common-references.txt diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt new file mode 100644 index 00000000..1a527590 --- /dev/null +++ b/docs/_include/interface-vlan-8021q.txt @@ -0,0 +1,120 @@ +IEEE 802.1q_, often referred to as Dot1q, is the networking standard that +supports virtual LANs (VLANs) on an IEEE 802.3 Ethernet network. The standard +defines a system of VLAN tagging for Ethernet frames and the accompanying +procedures to be used by bridges and switches in handling such frames. +The standard also contains provisions for a quality-of-service prioritization +scheme commonly known as IEEE 802.1p and defines the +Generic Attribute Registration Protocol. + +Portions of the network which are VLAN-aware (i.e., IEEE 802.1q_ conformant) can +include VLAN tags. When a frame enters the VLAN-aware portion of the network, a +tag is added to represent the VLAN membership. Each frame must be +distinguishable as being within exactly one VLAN. A frame in the VLAN-aware +portion of the network that does not contain a VLAN tag is assumed to be +flowing on the native VLAN. + +The standard was developed by IEEE 802.1, a working group of the IEEE 802 +standards committee, and continues to be actively revised. One of the notable +revisions is 802.1Q-2014 which incorporated IEEE 802.1aq +(Shortest Path Bridging) and much of the IEEE 802.1d standard. + +802.1q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The +term used for this is ``vif``. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> vif <vlan-id> + + Create a new VLAN interface on interface `<interface>` using the VLAN number + provided via `<vlan-id>`. + + You can create multiple VLAN interfaces on a physical interface. The VLAN ID + range is from 0 to 4094. + + .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. + +.. cmdinclude:: /_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-ip.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +**DHCP(v6)** + +.. cmdinclude:: /_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-dhcpv6-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. include:: /_include/common-references.txt diff --git a/docs/_include/interface-vrf.txt b/docs/_include/interface-vrf.txt new file mode 100644 index 00000000..1fa94f9f --- /dev/null +++ b/docs/_include/interface-vrf.txt @@ -0,0 +1,13 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} vrf <vrf> + + Place interface in given VRF instance. + + .. seealso:: There is an entire chapter about how to configure a :ref:`vrf`, + please check this for additional information. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} vrf red
\ No newline at end of file diff --git a/docs/_include/interface-xdp.txt b/docs/_include/interface-xdp.txt new file mode 100644 index 00000000..d87151fc --- /dev/null +++ b/docs/_include/interface-xdp.txt @@ -0,0 +1,27 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> xdp + + Enable support for Linux :abbr:`XDP (eXpress Data Path)` on recent 1.3 rolling + releases. You must enable it for every interface which should participate in + the XDP forwarding. + + XDP is an eBPF based high performance data path merged in the Linux kernel + since version 4.8. The idea behind XDP is to add an early hook in the RX path + of the kernel, and let a user supplied eBPF program decide the fate of the + packet. The hook is placed in the NIC driver just after the interrupt + processing, and before any memory allocation needed by the network stack + itself, because memory allocation can be an expensive operation. + + .. warning:: This is highly experimental! + + .. note:: Enabling this feature will break any form of NAT or Firewalling on + this interface, as XDP is handled way earlier in the driver then iptables/ + nftables. + + Enabling this feature will only load the XDP router code as described here: + https://blog.apnic.net/2020/04/30/how-to-build-an-xdp-based-bgp-peering-router/ + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} xdp
\ No newline at end of file diff --git a/docs/_include/need_improvement.txt b/docs/_include/need_improvement.txt index f7556465..1ce50685 100644 --- a/docs/_include/need_improvement.txt +++ b/docs/_include/need_improvement.txt @@ -8,8 +8,9 @@ <p class="admonition-title">Call for Contributions</p> -This page needs improvements, examples and explanations. -Please take a look at the Contributing Guide for :ref:`documentation`. +This section needs improvements, examples and explanations. + +Please take a look at the Contributing Guide for our :ref:`documentation`. .. raw:: html diff --git a/docs/_include/vyos-1x b/docs/_include/vyos-1x new file mode 160000 +Subproject 0dd41096f14771ffa476f52793308bffac51b59 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,12 +10,49 @@ 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%; + line-height: normal; background: #e7f2fa; color: #2980B9; border-top: solid 3px #6ab0de; @@ -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/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png Binary files differnew file mode 100644 index 00000000..bde1edb6 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing1.png diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png Binary files differnew file mode 100644 index 00000000..1111535d --- /dev/null +++ b/docs/_static/images/Wan_load_balancing_exclude1.png diff --git a/docs/_static/images/blueprint-dmvpn.png b/docs/_static/images/blueprint-dmvpn.png Binary files differnew file mode 100644 index 00000000..b07c190d --- /dev/null +++ b/docs/_static/images/blueprint-dmvpn.png diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png Binary files differnew file mode 100644 index 00000000..b00350bc --- /dev/null +++ b/docs/_static/images/boot-options.png diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg Binary files differnew file mode 100644 index 00000000..25fd72a9 --- /dev/null +++ b/docs/_static/images/sticky-connections.jpg diff --git a/docs/_static/images/vyos-logo.png b/docs/_static/images/vyos-logo.png Binary files differindex bc1abe15..e3d6f68b 100644 --- a/docs/_static/images/vyos-logo.png +++ b/docs/_static/images/vyos-logo.png diff --git a/docs/_static/images/vyos_1_4_nat66_simple.png b/docs/_static/images/vyos_1_4_nat66_simple.png Binary files differnew file mode 100644 index 00000000..d7c54115 --- /dev/null +++ b/docs/_static/images/vyos_1_4_nat66_simple.png diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png Binary files differnew file mode 100644 index 00000000..6c9ef8ec --- /dev/null +++ b/docs/_static/images/vyos_arista_bond_lacp.png diff --git a/docs/appendix/examples/dmvpn.rst b/docs/appendix/examples/dmvpn.rst deleted file mode 100644 index 44c08de4..00000000 --- a/docs/appendix/examples/dmvpn.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. _examples-dmvpn: - -######### -DMVPN Hub -######### - -General infomration can be found in the :ref:`vpn-dmvpn` chapter. - -Configuration -============= - -VyOS Hub --------- - -.. code-block:: none - - set interfaces tunnel tun100 address '172.16.253.134/29' - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 local-ip '203.0.113.44' - set interfaces tunnel tun100 multicast 'enable' - set interfaces tunnel tun100 parameters ip key '1' - - set protocols nhrp tunnel tun100 cisco-authentication <secret> - set protocols nhrp tunnel tun100 holding-time '300' - set protocols nhrp tunnel tun100 multicast 'dynamic' - set protocols nhrp tunnel tun100 redirect - set protocols nhrp tunnel tun100 shortcut - - set vpn ipsec esp-group ESP-HUB compression 'disable' - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'tunnel' - set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' - set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' - set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' - set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth0' - - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret <secret> - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' - -Cisco IOS Spoke ---------------- - -This example is verified with a Cisco 2811 platform running IOS 15.1(4)M9 and -VyOS 1.1.7 (helium) up to VyOS 1.2 (Crux). - -.. code-block:: none - - Cisco IOS Software, 2800 Software (C2800NM-ADVENTERPRISEK9-M), Version 15.1(4)M9, RELEASE SOFTWARE (fc3) - Technical Support: http://www.cisco.com/techsupport - Copyright (c) 1986-2014 by Cisco Systems, Inc. - Compiled Fri 12-Sep-14 10:45 by prod_rel_team - - ROM: System Bootstrap, Version 12.3(8r)T7, RELEASE SOFTWARE (fc1) - -Use this configuration on your Cisco device: - -.. code-block:: none - - crypto pki token default removal timeout 0 - crypto keyring DMVPN - pre-shared-key address 198.51.100.2 key <secretkey> - ! - crypto isakmp policy 10 - encr aes 256 - authentication pre-share - group 2 - ! - crypto isakmp invalid-spi-recovery - crypto isakmp keepalive 30 30 periodic - crypto isakmp profile DMVPN - keyring DMVPN - match identity address 203.0.113.44 255.255.255.255 - ! - crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac - mode transport - ! - crypto ipsec profile DMVPN - set security-association idle-time 720 - set transform-set DMVPN-AES256 - set isakmp-profile DMVPN - ! - interface Tunnel10 - description Tunnel to DMVPN HUB - ip address 172.16.253.129 255.255.255.248 - no ip redirects - ip nhrp authentication <nhrp secret key> - ip nhrp map multicast 203.0.113.44 - ip nhrp map 172.16.253.134 203.0.113.44 - ip nhrp network-id 1 - ip nhrp holdtime 600 - ip nhrp nhs 172.16.253.134 - ip nhrp registration timeout 75 - tunnel source Dialer1 - tunnel mode gre multipoint - tunnel key 1 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` <regex> 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 <IPv4 net|IPv6 net>" - 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 <intf>" 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 <https://web.archive.org/web/20200212180711/https://wiki.vyos.net/wiki/Category:Release_notes>`_. 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/appendix/vyos-on-vmware.rst b/docs/appendix/vyos-on-vmware.rst deleted file mode 100644 index c4299cbf..00000000 --- a/docs/appendix/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/command-scripting.rst b/docs/automation/command-scripting.rst index 7d0ab6c5..7d0ab6c5 100644 --- a/docs/appendix/command-scripting.rst +++ b/docs/automation/command-scripting.rst diff --git a/docs/automation/index.rst b/docs/automation/index.rst new file mode 100644 index 00000000..e07dfecc --- /dev/null +++ b/docs/automation/index.rst @@ -0,0 +1,15 @@ +############### +VyOS Automation +############### + + + * Ansible + * Saltstack + * HTTP-API + * startup scripts + + +.. toctree:: + :maxdepth: 1 + + command-scripting
\ 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 <IPv4 net|IPv6 net>" + 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 <intf>" 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..3e228880 --- /dev/null +++ b/docs/changelog/1.2.4.rst @@ -0,0 +1,77 @@ +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. + (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 passwor + 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 prevent + load balancing from starting +* :vytask:`T1568` strip-private command improvement for additional masking o + 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 recen + 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 + 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` <regex> 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.p + 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 migratio + failed: module=l2tp +* :vytask:`T1812` DHCP: hostnames of clients not resolving afte + 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..438e84f2 --- /dev/null +++ b/docs/changelog/1.2.5.rst @@ -0,0 +1,70 @@ +1.2.5 +===== + +1.2.5 is a maintenance release made in April 2020. + +Resolved issues +--------------- + +* :vytask:`T1020` OSPF Stops distributing default route after a while +* :vytask:`T1228` pppoe default-route force option not working (Rel 1.2.0-rc11) +* :vytask:`T1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. +* :vytask:`T1341` Adding rate-limiter for pppoe server users +* :vytask:`T1376` Incorrect DHCP lease counting +* :vytask:`T1392` Large firewall rulesets cause the system to lose configuration + and crash at startup +* :vytask:`T1416` 2 dhcp server run in failover mode can't sync hostname with + each other +* :vytask:`T1452` accel-pppoe - add vendor option to shaper +* :vytask:`T1490` BGP configuration (is lost|not applied) when updating + 1.1.8 -> 1.2.1 +* :vytask:`T1780` Adding ipsec ike closeaction +* :vytask:`T1803` Unbind NTP while it's not requested... +* :vytask:`T1821` "authentication mode radius" has no effect for PPPoE server +* :vytask:`T1827` Increase default gc_thresh +* :vytask:`T1828` Missing completion helper for "set system syslog host + 192.0.2.1 facility all protocol" +* :vytask:`T1832` radvd adding feature DNSSL branch.example.com example.com to + existing package +* :vytask:`T1837` PPPoE unrecognized option 'replacedefaultroute' +* :vytask:`T1851` wireguard - changing the pubkey on an existing peer seems to + destroy the running config. +* :vytask:`T1858` l2tp: Delete depricated outside-nexthop and add gateway-address +* :vytask:`T1864` Lower IPSec DPD timeout lower limit from 10s -> 2s +* :vytask:`T1879` Extend Dynamic DNS XML definition value help strings and + validators +* :vytask:`T1881` Execute permissions are removed from custom SNMP scripts at + commit time +* :vytask:`T1884` Keeping VRRP transition-script native behaviour and adding + stop-script +* :vytask:`T1891` Router announcements broken on boot +* :vytask:`T1900` Enable SNMP for VRRP. +* :vytask:`T1902` Add redistribute non main table in bgp +* :vytask:`T1909` Incorrect behaviour of static routes with overlapping networks +* :vytask:`T1913` "system ipv6 blacklist" command has no effect +* :vytask:`T1914` IPv6 multipath hash policy does not apply +* :vytask:`T1917` Update WireGuard to Debian release 0.0.20191219-1 +* :vytask:`T1934` Change default hostname when deploy from OVA without params. +* :vytask:`T1935` NIC identification and usage problem in Hyper-V environments +* :vytask:`T1936` pppoe-server CLI control features +* :vytask:`T1964` SNMP Script-extensions allows names with spaces, but commit + fails +* :vytask:`T1967` BGP parameter "enforce-first-as" does not work anymore +* :vytask:`T1970` Correct adding interfaces on boot +* :vytask:`T1971` Missing modules in initrd.img for PXE boot +* :vytask:`T1998` Update FRR to 7.3 +* :vytask:`T2001` Error when router reboot +* :vytask:`T2032` Monitor bandwidth bits +* :vytask:`T2059` Set source-validation on bond vif don't work +* :vytask:`T2066` PPPoE interface can be created multiple times - last wins +* :vytask:`T2069` PPPoE-client does not works with service-name option +* :vytask:`T2077` ISO build from crux branch is failing +* :vytask:`T2079` Update Linux Kernel to v4.19.106 +* :vytask:`T2087` Add maxfail 0 option to pppoe configuration. +* :vytask:`T2100` BGP route adverisement wih checks rib +* :vytask:`T2120` "reset vpn ipsec-peer" doesn't work with named peers +* :vytask:`T2197` Cant add vif-s interface into a bridge +* :vytask:`T2228` WireGuard does not allow ports < 1024 to be used +* :vytask:`T2252` HTTP API add system image can return '504 Gateway Time-out' +* :vytask:`T2272` Set system flow-accounting disable-imt has syntax error +* :vytask:`T2276` PPPoE server vulnerability
\ No newline at end of file diff --git a/docs/changelog/1.2.6.rst b/docs/changelog/1.2.6.rst new file mode 100644 index 00000000..8ea92657 --- /dev/null +++ b/docs/changelog/1.2.6.rst @@ -0,0 +1,106 @@ +1.2.6-S1 +======== + +1.2.6-S1 is a security release release made in September 2020. + +Resolved issues +--------------- + +VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- +impact vulnerability in the PowerDNS recursor that allows an attacker to cause +performance degradation via a specially crafted authoritative DNS server reply. + +* :vytask:`T2899` remote syslog server migration error on update + +1.2.6 +===== + +1.2.6 is a maintenance release made in September 2020. + +Resolved issues +--------------- + +* :vytask:`T103` DHCP server prepends shared network name to hostnames +* :vytask:`T125` Missing PPPoE interfaces in l2tp configuration +* :vytask:`T1194` cronjob is being setup even if not saved +* :vytask:`T1205` module pcspkr missing +* :vytask:`T1219` Redundant active-active configuration, asymmetric routing and + conntrack-sync cache +* :vytask:`T1220` Show transceiver information from plugin modules, e.g SFP+, + QSFP +* :vytask:`T1221` BGP - Default route injection is not processed by the specific + route-map +* :vytask:`T1241` Remove of policy route throws CLI error +* :vytask:`T1291` Under certain conditions the VTI will stay forever down +* :vytask:`T1463` Missing command `show ip bgp scan` appears in command + completion +* :vytask:`T1575` `show snmp mib ifmib` crashes with IndexError +* :vytask:`T1699` Default net.ipv6.route.max_size 32768 is too low +* :vytask:`T1729` PIM (Protocol Independent Multicast) implementation +* :vytask:`T1901` Semicolon in values is interpreted as a part of the shell + command by validators +* :vytask:`T1934` Change default hostname when deploy from OVA without params. +* :vytask:`T1938` syslog doesn't start automatically +* :vytask:`T1949` Multihop IPv6 BFD is unconfigurable +* :vytask:`T1953` DDNS service name validation rejects valid service names +* :vytask:`T1956` PPPoE server: support PADO-delay +* :vytask:`T1973` Allow route-map to match on BGP local preference value +* :vytask:`T1974` Allow route-map to set administrative distance +* :vytask:`T1982` Increase rotation for atop.acct +* :vytask:`T1983` Expose route-map when BGP routes are programmed in to FIB +* :vytask:`T1985` pppoe: Enable ipv6 modules without configured ipv6 pools +* :vytask:`T2000` strongSwan does not install routes to table 220 in certain + cases +* :vytask:`T2021` OSPFv3 doesn't support decimal area syntax +* :vytask:`T2062` Wrong dhcp-server static route subnet bytes +* :vytask:`T2091` swanctl.conf file is not generated properly is more than one + IPsec profile is used +* :vytask:`T2131` Improve syslog remote host CLI definition +* :vytask:`T2224` Update Linux Kernel to v4.19.114 +* :vytask:`T2286` IPoE server vulnerability +* :vytask:`T2303` Unable to delete the image version that came from OVA +* :vytask:`T2305` Add release name to "show version" command +* :vytask:`T2311` Statically configured name servers may not take precedence + over ones from DHCP +* :vytask:`T2327` Unable to create syslog server entry with different port +* :vytask:`T2332` Backport node option for a syslog server +* :vytask:`T2342` Bridge l2tpv3 + ethX errors +* :vytask:`T2344` PPPoE server client static IP assignment silently fails +* :vytask:`T2385` salt-minion: improve completion helpers +* :vytask:`T2389` BGP community-list unknown command +* :vytask:`T2398` op-mode "dhcp client leases interface" completion helper + misses interfaces +* :vytask:`T2402` Live ISO should warn when configuring that changes won't + persist +* :vytask:`T2443` NHRP: Add debugging information to syslog +* :vytask:`T2448` `monitor protocol bgp` subcommands fail with 'command + incomplete' +* :vytask:`T2458` Update FRR to 7.3.1 +* :vytask:`T2476` Bond member description change leads to network outage +* :vytask:`T2478` login radius: use NAS-IP-Address if defined source address +* :vytask:`T2482` Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 +* :vytask:`T2517` vyos-container: link_filter: No such file or directory +* :vytask:`T2526` Wake-On-Lan CLI implementation +* :vytask:`T2528` "update dns dynamic" throws FileNotFoundError excepton +* :vytask:`T2536` "show log dns forwarding" still refers to dnsmasq +* :vytask:`T2538` Update Intel NIC drivers to recent release (preparation for + Kernel >=5.4) +* :vytask:`T2545` Show physical device offloading capabilities for specified + ethernet interface +* :vytask:`T2563` Wrong interface binding for Dell VEP 1445 +* :vytask:`T2605` SNMP service is not disabled by default +* :vytask:`T2625` Provide generic Library for package builds +* :vytask:`T2686` FRR: BGP: large-community configuration is not applied + properly after upgrading FRR to 7.3.x series +* :vytask:`T2701` `vpn ipsec pfs enable` doesn't work with IKE groups +* :vytask:`T2728` Protocol option ignored for IPSec peers in transport mode +* :vytask:`T2734` WireGuard: fwmark CLI definition is inconsistent +* :vytask:`T2757` "show system image version" contains additional new-line + character breaking output +* :vytask:`T2797` Update Linux Kernel to v4.19.139 +* :vytask:`T2822` Update Linux Kernel to v4.19.141 +* :vytask:`T2829` PPPoE server: mppe setting is implemented as node instead of + leafNode +* :vytask:`T2831` Update Linux Kernel to v4.19.142 +* :vytask:`T2852` rename dynamic dns interface breaks ddclient.cache permissions +* :vytask:`T2853` Intel QAT acceleration does not work
\ No newline at end of file diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst new file mode 100644 index 00000000..ae964145 --- /dev/null +++ b/docs/changelog/index.rst @@ -0,0 +1,18 @@ +.. _release-notes: + + +######### +Changelog +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + 1.2.6 + 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..7578ef8d 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,19 +1,18 @@ .. _cli: -### -CLI -### +###################### +Command 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 -modification of system configuration. The list of all operational level commands -is available at :ref:`operational_level_commands`. +modification of system configuration. The CLI provides a built-in help system. In the CLI the ``?`` key may be used to display available commands. The ``TAB`` key can be used to auto-complete @@ -73,10 +72,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`. +################## To enter configuration mode use the ``configure`` command: @@ -97,3 +93,737 @@ To enter configuration mode use the ``configure`` command: See the configuration section of this document for more information on configuration mode. + + +.. _configuration-overview: + +###################### +Configuration Overview +###################### + +VyOS makes use of a unified configuration file for the entire system's +configuration: ``/config/config.boot``. This allows easy template +creation, backup, and replication of system configuration. A system can +thus also be easily cloned by simply copying the required configuration +files. + +Terminology +########### + +live +A VyOS system has three major types of configurations: + +* **Active** or **running configuration** is the system configuration + that is loaded and currently active (used by VyOS). Any change in + the configuration will have to be committed to belong to the + active/running configuration. + +* **Working configuration** is the one that is currently being modified + in configuration mode. Changes made to the working configuration do + not go into effect until the changes are committed with the + :cfgcmd:`commit` command. At which time the working configuration will + become the active or running configuration. + +* **Saved configuration** is the one saved to a file using the + :cfgcmd:`save` command. It allows you to keep safe a configuration for + future uses. There can be multiple configuration files. The default or + "boot" configuration is saved and loaded from the file + ``/config/config.boot``. + +Seeing and navigating the configuration +======================================= + +.. opcmd:: show configuration + + View the current active configuration, also known as the running + configuration, from the operational mode. + + .. code-block:: none + + vyos@vyos:~$ show configuration + interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } + } + service { + ssh { + port 22 + } + } + system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } + } + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the +configuration. When the configuration is generated and the device is +configured, changes are added through a collection of :cfgcmd:`set` and +:cfgcmd:`delete` commands. + +.. opcmd:: show configuration commands + + Get a collection of all the set commands required which led to the + running configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration commands + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' + set interfaces loopback 'lo' + set service ssh port '22' + set system config-management commit-revisions '20' + set system console device ttyS0 speed '9600' + set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' + set system login user vyos level 'admin' + set system ntp server '0.pool.ntp.org' + set system ntp server '1.pool.ntp.org' + set system ntp server '2.pool.ntp.org' + set system syslog global facility all level 'notice' + set system syslog global facility protocols level 'debug' + +Both these ``show`` commands should be executed when in operational +mode, they do not work directly in configuration mode. There is a +special way on how to :ref:`run_opmode_from_config_mode`. + +.. hint:: Use the ``show configuration commands | strip-private`` + command when you want to hide private data. You may want to do so if + you want to share your configuration on the `forum`_. + +.. _`forum`: https://forum.vyos.io + + +The config mode +--------------- + +When entering the configuration mode you are navigating inside a tree +structure, to enter configuration mode enter the command +:opcmd:`configure` when in operational mode. + +.. code-block:: none + + vyos@vyos$ configure + [edit] + vyos@vyos# + + +.. note:: When going into configuration mode, prompt changes from + ``$`` to ``#``. + + +All commands executed here are relative to the configuration level you +have entered. You can do everything from the top level, but commands +will be quite lengthy when manually typing them. + +The current hierarchy level can be changed by the :cfgcmd:`edit` +command. + +.. code-block:: none + + [edit] + vyos@vyos# edit interfaces ethernet eth0 + + [edit interfaces ethernet eth0] + vyos@vyos# + +You are now in a sublevel relative to ``interfaces ethernet eth0``, all +commands executed from this point on are relative to this sublevel. Use +eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top +of the hierarchy. You can also use the :cfgcmd:`up` command to move only +one level up at a time. + +.. cfgcmd:: show + +The :cfgcmd:`show` command within configuration mode will show the +working configuration indicating line changes with ``+`` for additions, +``>`` for replacements and ``-`` for deletions. + +**Example:** + +.. code-block:: none + + vyos@vyos:~$ configure + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + description MY_OLD_DESCRIPTION + disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + [edit] + vyos@vyos# set interfaces ethernet eth0 address dhcp + [edit] + vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION + [edit] + vyos@vyos# delete interfaces ethernet eth0 disable + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + + address dhcp + > description MY_NEW_DESCRIPTION + - disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + +It is also possible to display all `set` commands within configuration +mode using :cfgcmd:`show | commands` + +.. code-block:: none + + vyos@vyos# show interfaces ethernet eth0 | commands + set address dhcp + set hw-id 00:53:ad:44:3b:03 + +These commands are also relative to the level you are inside and only +relevant configuration blocks will be displayed when entering a +sub-level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# show + address dhcp + hw-id 00:53:ad:44:3b:03 + +Exiting from the configuration mode is done via the :cfgcmd:`exit` +command from the top level, executing :cfgcmd:`exit` from within a +sub-level takes you back to the top level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + + +Editing the configuration +========================= + +The configuration can be edited by the use of :cfgcmd:`set` and +:cfgcmd:`delete` commands from within configuration mode. + +.. cfgcmd:: set + + Use this command to set the value of a parameter or to create a new + element. + +Configuration commands are flattened from the tree into 'one-liner' +commands shown in :opcmd:`show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all +redundant information from the current level is removed from the command +entered. + +.. code-block:: none + + [edit] + vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 + + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# set address 203.0.113.6/24 + + +These two commands above are essentially the same, just executed from +different levels in the hierarchy. + +.. cfgcmd:: delete + + To delete a configuration entry use the :cfgcmd:`delete` command, + this also deletes all sub-levels under the current level you've + specified in the :cfgcmd:`delete` command. Deleting an entry will + also result in the element reverting back to its default value if one + exists. + + .. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# delete address 192.0.2.100/24 + +.. cfgcmd:: commit + + Any change you do on the configuration, will not take effect until + committed using the :cfgcmd:`commit` command in configuration mode. + + .. code-block:: none + + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ + +.. _save: + +.. cfgcmd:: save + + Use this command to preserve configuration changes upon reboot. By + default it is stored at */config/config.boot*. In the case you want + to store the configuration file somewhere else, you can add a local + path, an SCP address, an FTP address or a TFTP address. + + .. code-block:: none + + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + + .. code-block:: none + + vyos@vyos# save [tab] + Possible completions: + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>:/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine + vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot + Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... + ######################################################################## 100.0% + Done + +.. cfgcmd:: exit [discard] + + Configuration mode can not be exited while uncommitted changes exist. + To exit configuration mode without applying changes, the + :cfgcmd:`exit discard` command must be used. + + All changes in the working config will thus be lost. + + .. code-block:: none + + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# exit discard + + +.. cfgcmd:: commit-confirm <minutes> + + Use this command to temporarily commit your changes and set the + number of minutes available for validation. ``confirm`` must + be entered within those minutes, otherwise the system will reboot + into the previous configuration. The default value is 10 minutes. + + + What if you are doing something dangerous? Suppose you want to setup + a firewall, and you are not sure there are no mistakes that will lock + you out of your system. You can use confirmed commit. If you issue + the ``commit-confirm`` command, your changes will be commited, and if + you don't issue issue the ``confirm`` command in 10 minutes, your + system will reboot into previous config revision. + + .. code-block:: none + + vyos@router# set interfaces ethernet eth0 firewall local name FromWorld + vyos@router# commit-confirm + commit confirm will be automatically reboot in 10 minutes unless confirmed + Proceed? [confirm]y + [edit] + vyos@router# confirm + [edit] + + + .. note:: A reboot because you did not enter ``confirm`` will not + take you necessarily to the *saved configuration*, but to the + point before the unfortunate commit. + + +.. cfgcmd:: copy + + Copy a configuration element. + + You can copy and remove configuration subtrees. Suppose you set up a + firewall ruleset ``FromWorld`` with one rule that allows traffic from + specific subnet. Now you want to setup a similar rule, but for + different subnet. Change your edit level to + ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then + modify rule 20. + + + .. code-block:: none + + vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } + [edit] + vyos@router# edit firewall name FromWorld + [edit firewall name FromWorld] + vyos@router# copy rule 10 to rule 20 + [edit firewall name FromWorld] + vyos@router# set rule 20 source address 198.51.100.0/24 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + +.. cfgcmd:: rename + + Rename a configuration element. + + You can also rename config subtrees: + + .. code-block:: none + + vyos@router# rename rule 10 to rule 5 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + Note that ``show`` command respects your edit level and from this + level you can view the modified firewall ruleset with just ``show`` + with no parameters. + + .. code-block:: none + + vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } + + +.. cfgcmd:: comment <config node> "comment text" + + Add comment as an annotation to a configuration node. + + The ``comment`` command allows you to insert a comment above the + ``<config node>`` configuration section. When shown, comments are + enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments + need to be commited, just like other config changes. + + To remove an existing comment from your current configuration, + specify an empty string enclosed in double quote marks (``""``) as + the comment text. + + Example: + + .. code-block:: none + + vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" + vyos@vyos# commit + vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } + + .. note:: An important thing to note is that since the comment is + added on top of the section, it will not appear if the ``show + <section>`` command is used. With the above example, the `show + firewall` command would return starting after the ``firewall + {`` line, hiding the comment. + + + + + + +.. _run_opmode_from_config_mode: + +Access opmode from config mode +============================== + +When inside configuration mode you are not directly able to execute +operational commands. + +.. cfgcmd:: run + + Access to these commands are possible through the use of the + ``run [command]`` command. From this command you will have access to + everything accessible from operational mode. + + Command completion and syntax help with ``?`` and ``[tab]`` will also + work. + + .. code-block:: none + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 0.0.0.0/0 u/u + +Managing configurations +======================= + +VyOS comes with an integrated versioning system for the system +configuration. It automatically maintains a backup of every previous +configuration which has been committed to the system. The configurations +are versioned locally for rollback but they can also be stored on a +remote host for archiving/backup reasons. + +Local Archive +------------- + +Revisions are stored on disk. You can view, compare and rollback them to +any previous revisions if something goes wrong. + +.. opcmd:: show system commit + + View all existing revisions on the local system. + + .. code-block:: none + + vyos@vyos:~$ show system commit + 0 2015-03-30 08:53:03 by vyos via cli + 1 2015-03-30 08:52:20 by vyos via cli + 2 2015-03-26 21:26:01 by root via boot-config-loader + 3 2015-03-26 20:43:18 by root via boot-config-loader + 4 2015-03-25 11:06:14 by root via boot-config-loader + 5 2015-03-25 01:04:28 by root via boot-config-loader + 6 2015-03-25 00:16:47 by vyos via cli + 7 2015-03-24 23:43:45 by root via boot-config-loader + + +.. cfgcmd:: set system config-management commit-revisions <N> + + You can specify the number of revisions stored on disk. N can be in + the range of 0 - 65535. When the number of revisions exceeds the + configured value, the oldest revision is removed. The default setting + for this value is to store 100 revisions locally. + + +Compare configurations +---------------------- + +VyOS lets you compare different configurations. + +.. cfgcmd:: compare <saved | N> <M> + + Use this command to spot what the differences are between different + configurations. + + .. code-block:: none + + vyos@vyos# compare [tab] + Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + The command :cfgcmd:`compare` allows you to compare different type of + configurations. It also lets you compare different revisions through + the :cfgcmd:`compare N M` command, where N and M are revision + numbers. The output will describe how the configuration N is when + compared to M indicating with a plus sign (``+``) the additional + parts N has when compared to M, and indicating with a minus sign + (``-``) the lacking parts N misses when compared to M. + + .. code-block:: none + + vyos@vyos# compare 0 6 + [edit interfaces] + +dummy dum1 { + + address 10.189.0.1/31 + +} + [edit interfaces ethernet eth0] + +vif 99 { + + address 10.199.0.1/31 + +} + -vif 900 { + - address 192.0.2.4/24 + -} + + +.. opcmd:: show system commit diff <number> + + Show commit revision difference. + + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +.. code-block:: none + + vyos@router# run show system commit diff 4 + [edit system] + +ipv6 { + + disable-forwarding + +} + +This means four commits ago we did ``set system ipv6 disable-forwarding``. + + +Rollback Changes +---------------- + +You can rollback configuration changes using the rollback command. This +will apply the selected revision and trigger a system reboot. + +.. cfgcmd:: rollback <N> + + Rollback to revision N (currently requires reboot) + + .. code-block:: none + + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] + + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! + +Remote Archive +-------------- + +VyOS can upload the configuration to a remote location after each call +to :cfgcmd:`commit`. You will have to set the commit-archive location. +TFTP, FTP, SCP and SFTP servers are supported. Every time a +:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied +to the defined destination(s). The filename used on the remote host will +be ``config.boot-hostname.YYYYMMDD_HHMMSS``. + +.. cfgcmd:: set system config-management commit-archive location <URI> + + Specify remote location of commit archive as any of the below + :abbr:`URI (Uniform Resource Identifier)` + + * ``scp://<user>:<passwd>@<host>:/<dir>`` + * ``sftp://<user>:<passwd>@<host>/<dir>`` + * ``ftp://<user>:<passwd>@<host>/<dir>`` + * ``tftp://<host>/<dir>`` + +.. note:: The number of revisions don't affect the commit-archive. + +.. note:: You may find VyOS not allowing the secure connection because + it cannot verify the legitimacy of the remote server. You can use + the workaround below to quickly add the remote host's SSH + fingerprint to your ``~/.ssh/known_hosts`` file: + + .. code-block:: none + + vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts + +Saving and loading manually +--------------------------- + +You can use the ``save`` and ``load`` commands if you want to manually +manage specific configuration files. + +When using the save_ command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the ``load`` command: + +.. cfgcmd:: load <URI> + + Use this command to load a configuration which will replace the + running configuration. Define the location of the configuration file + to be loaded. You can use a path to a local file, an SCP address, an + SFTP address, an FTP address, an HTTP address, an HTTPS address or a + TFTP address. + + .. code-block:: none + + vyos@vyos# load + Possible completions: + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>:/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + + + +Restore Default +--------------- + +In the case you want to completely delete your configuration and restore +the default one, you can enter the following command in configuration +mode: + +.. code-block:: none + + load /opt/vyatta/etc/config.boot.default + +You will be asked if you want to continue. If you accept, you will have +to use :cfgcmd:`commit` if you want to make the changes active. + +Then you may want to :cfgcmd:`save` in order to delete the saved +configuration too. + +.. note:: If you are remotely connected, you will lose your connection. + You may want to copy first the config, edit it to ensure + connectivity, and load the edited config. + diff --git a/docs/command-list-configuration.rst b/docs/command-list-configuration.rst deleted file mode 100644 index 7b981518..00000000 --- a/docs/command-list-configuration.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _configuration_level_commands: - -******************************** -Configuration Level Command List -******************************** - -.. cfgcmdlist:: diff --git a/docs/command-list-operation.rst b/docs/command-list-operation.rst deleted file mode 100644 index bbb0298c..00000000 --- a/docs/command-list-operation.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _operational_level_commands: - -****************************** -Operational Level Command List -****************************** - -.. opcmdlist:: diff --git a/docs/conf.py b/docs/conf.py index bb32aa33..594d6063 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,14 +22,14 @@ from docutils.parsers.rst.roles import set_classes # -- Project information ----------------------------------------------------- project = u'VyOS' -copyright = u'2020, VyOS maintainers and contributors' +copyright = u'2021, 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' diff --git a/docs/appendix/examples/azure-vpn-bgp.rst b/docs/configexamples/azure-vpn-bgp.rst index 176e0ae0..1d61b3b8 100644 --- a/docs/appendix/examples/azure-vpn-bgp.rst +++ b/docs/configexamples/azure-vpn-bgp.rst @@ -6,7 +6,9 @@ Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) This guide shows an example of a route-based IKEv2 site-to-site VPN to Azure using VTI and BGP for dynamic routing updates. -For redundant / active-active configurations see `Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) <https://docs.vyos.io/en/crux/appendix/examples/azure-vpn-dual-bgp.html>`_ +For redundant / active-active configurations see +:ref:`examples-azure-vpn-dual-bgp` + Prerequisites ^^^^^^^^^^^^^ @@ -112,7 +114,7 @@ Vyos configuration .. code-block:: none - set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + set protocols static route 10.0.0.4/32 interface vti1 - Configure your BGP settings diff --git a/docs/appendix/examples/azure-vpn-dual-bgp.rst b/docs/configexamples/azure-vpn-dual-bgp.rst index 13d4b5a2..0a48156c 100644 --- a/docs/appendix/examples/azure-vpn-dual-bgp.rst +++ b/docs/configexamples/azure-vpn-dual-bgp.rst @@ -129,8 +129,8 @@ Vyos configuration .. code-block:: none - set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 - set protocols static interface-route 10.0.0.5/32 next-hop-interface vti2 + set protocols static route 10.0.0.4/32 interface vti1 + set protocols static route 10.0.0.5/32 interface vti2 - Configure your BGP settings diff --git a/docs/appendix/examples/bgp-ipv6-unnumbered.rst b/docs/configexamples/bgp-ipv6-unnumbered.rst index ccc1f69a..ccc1f69a 100644 --- a/docs/appendix/examples/bgp-ipv6-unnumbered.rst +++ b/docs/configexamples/bgp-ipv6-unnumbered.rst diff --git a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst b/docs/configexamples/dhcp-relay-through-gre-bridge.rst index f94eb67f..afa4d854 100644 --- a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst +++ b/docs/configexamples/dhcp-relay-through-gre-bridge.rst @@ -21,18 +21,18 @@ DHCP Server .. code-block:: none set interfaces ethernet eth0 address '10.0.2.1/24' - set interfaces loopback lo address '3.3.3.3/24' + set interfaces loopback lo address '192.168.3.3/24' set interfaces tunnel tun100 address '172.16.0.2/30' set interfaces tunnel tun100 encapsulation 'gre-bridge' set interfaces tunnel tun100 local-ip '10.0.2.1' set interfaces tunnel tun100 remote-ip '192.168.0.1' - set protocols ospf area 0 network '3.3.3.0/24' + set protocols ospf area 0 network '192.168.3.0/24' set protocols ospf area 0 network '10.0.2.0/24' - set protocols ospf parameters router-id '3.3.3.3' - set protocols static interface-route 10.0.1.2/32 next-hop-interface tun100 + set protocols ospf parameters router-id '192.168.3.3' + set protocols static route 10.0.1.2/32 interface tun100 set service dhcp-server shared-network-name asdf authoritative - set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 start '3.3.3.30' - set service dhcp-server shared-network-name asdf subnet 3.3.3.0/24 range 0 stop '3.3.3.40' + set service dhcp-server shared-network-name asdf subnet 192.168.3.0/24 range 0 start '192.168.3.30' + set service dhcp-server shared-network-name asdf subnet 192.168.3.0/24 range 0 stop '192.168.3.40' set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 default-router '10.0.1.2' set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 start '10.0.1.200' set service dhcp-server shared-network-name asdf subnet 10.0.1.0/24 range 0 stop '10.0.1.210' @@ -61,17 +61,17 @@ DHCP Relay set interfaces ethernet eth0 address '10.0.1.2/24' set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces loopback lo address '1.1.1.1' + set interfaces loopback lo address '10.100.100.1' set interfaces tunnel tun100 address '172.16.0.1/30' set interfaces tunnel tun100 encapsulation 'gre-bridge' set interfaces tunnel tun100 local-ip '192.168.0.1' set interfaces tunnel tun100 remote-ip '10.0.2.1' set protocols ospf area 0 network '10.0.1.0/24' set protocols ospf area 0 network '192.168.0.0/24' - set protocols ospf area 0 network '1.1.1.0/24' - set protocols ospf parameters router-id '1.1.1.1' - set protocols static interface-route 3.3.3.3/32 next-hop-interface tun100 + set protocols ospf area 0 network '10.100.100.0/24' + set protocols ospf parameters router-id '10.100.100.1' + set protocols static route 192.168.3.3/32 interface tun100 set service dhcp-relay interface 'eth0' set service dhcp-relay interface 'tun100' - set service dhcp-relay server '3.3.3.3' + set service dhcp-relay server '192.168.3.3' diff --git a/docs/appendix/examples/ha.rst b/docs/configexamples/ha.rst index 702cb2b2..702cb2b2 100644 --- a/docs/appendix/examples/ha.rst +++ b/docs/configexamples/ha.rst diff --git a/docs/appendix/examples/index.rst b/docs/configexamples/index.rst index ca3a6251..b2f7bfde 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/configexamples/index.rst @@ -3,13 +3,11 @@ Configuration Blueprints ======================== -This chapter contains various configuration Examples - +This chapter contains various configuration examples: .. toctree:: :maxdepth: 2 - dmvpn dhcp-relay-through-gre-bridge zone-policy bgp-ipv6-unnumbered @@ -18,3 +16,4 @@ This chapter contains various configuration Examples azure-vpn-dual-bgp tunnelbroker-ipv6 ha + wan-load-balancing diff --git a/docs/appendix/examples/ospf-unnumbered.rst b/docs/configexamples/ospf-unnumbered.rst index 39f8f69a..dfb4eec1 100644 --- a/docs/appendix/examples/ospf-unnumbered.rst +++ b/docs/configexamples/ospf-unnumbered.rst @@ -4,7 +4,7 @@ OSPF unnumbered with ECMP ######################### -General infomration can be found in the :ref:`routing-ospf` chapter. +General information can be found in the :ref:`routing-ospf` chapter. Configuration ============= diff --git a/docs/appendix/examples/tunnelbroker-ipv6.rst b/docs/configexamples/tunnelbroker-ipv6.rst index 868b225f..1df814dc 100644 --- a/docs/appendix/examples/tunnelbroker-ipv6.rst +++ b/docs/configexamples/tunnelbroker-ipv6.rst @@ -1,5 +1,7 @@ .. _examples-tunnelbroker-ipv6: +.. stop_vyoslinter + ####################### Tunnelbroker.net (IPv6) ####################### @@ -33,7 +35,7 @@ tunnel information page. set interfaces tunnel tun0 mtu '1472' set interfaces tunnel tun0 multicast 'disable' set interfaces tunnel tun0 remote-ip Server_IPv4_from_Tunnelbroker # This is the IP of the Tunnelbroker server - set protocols static interface-route6 ::/0 next-hop-interface tun0 # Tell all traffic to go over this tunnel + set protocols static route6 ::/0 interface tun0 # Tell all traffic to go over this tunnel commit If your WAN connection is over PPPoE, you may need to set the MTU on the above @@ -110,7 +112,9 @@ should be replaced with the information from your `Routed /64` tunnel): set service router-advert interface eth1 name-server '2001:4860:4860::8844' set service router-advert interface eth1 prefix 2001:470:xxxx:xxxx::/64 -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. This accomplishes a few things: @@ -155,7 +159,9 @@ So, when your LAN is eth1, your DMZ is eth2, your cameras live on eth3, etc: set service router-advert interface eth3 name-server '2001:4860:4860::8844' set service router-advert interface eth3 prefix 2001:470:xxxx:3::/64 -Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, 'valid-lifetime' and 'preferred-lifetime' are set to default values of 30 days and 4 hours respectively. +Please note, 'autonomous-flag' and 'on-link-flag' are enabled by default, +'valid-lifetime' and 'preferred-lifetime' are set to default values of +30 days and 4 hours respectively. Firewall ======== @@ -167,3 +173,6 @@ NAME`. Similarly, to attach the firewall, you would use `set interfaces ethernet eth0 firewall in ipv6-name` or `set zone-policy zone LOCAL from WAN firewall ipv6-name`. + + +.. start_vyoslinter diff --git a/docs/configexamples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst new file mode 100644 index 00000000..07974166 --- /dev/null +++ b/docs/configexamples/wan-load-balancing.rst @@ -0,0 +1,174 @@ +.. _wan-load-balancing: + +.. stop_vyoslinter # pictures and text have to change + +WAN Load Balancer examples +========================== + + +Example 1: Distributing load evenly +----------------------------------- + +The setup used in this example is shown in the following diagram: + +.. image:: /_static/images/Wan_load_balancing1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + + +Overview +^^^^^^^^ + * All traffic coming in trough eth2 is balanced between eth0 and eth1 + on the router. + * Pings will be sent to four targets for health testing (33.44.55.66, + 44.55.66.77, 55.66.77.88 and 66.77.88.99). + * All outgoing packets are assigned the source address of the assigned + interface (SNAT). + * eth0 is set to be removed from the load balancer's interface pool + after 5 ping failures, eth1 will be removed after 4 ping failures. + +Create static routes to ping targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +.. code-block:: none + + set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 + set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 + set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 + set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 + +Configure the load balancer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure the WAN load balancer with the parameters described above: + +.. code-block:: none + + set load-balancing wan interface-health eth0 failure-count 5 + set load-balancing wan interface-health eth0 nexthop 11.22.33.1 + set load-balancing wan interface-health eth0 test 10 type ping + set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 + set load-balancing wan interface-health eth0 test 20 type ping + set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 + set load-balancing wan interface-health eth1 failure-count 4 + set load-balancing wan interface-health eth1 nexthop 22.33.44.1 + set load-balancing wan interface-health eth1 test 10 type ping + set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 + set load-balancing wan interface-health eth1 test 20 type ping + set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 10 interface eth1 + +Example 2: Failover based on interface weights +---------------------------------------------- + +This examples uses the failover mode. + +Overview +^^^^^^^^ +In this example eth0 is the primary interface and eth1 is the secondary +interface to provide simple failover functionality. If eth0 fails, eth1 +takes over. + +Create interface weight based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The configuration steps are the same as in the previous example, except +rule 10 so we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 failover + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 weight 10 + set load-balancing wan rule 10 interface eth1 weight 1 + +Example 3: Failover based on rule order +--------------------------------------- + +The previous example used the failover command to send traffic thorugh +eth1 if eth0 fails. In this example failover functionality is provided +by rule order. + +Overview +^^^^^^^^ +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +Create rule order based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configurtation from the previous example, delete rule 10 +and create the two new rules as described: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + +Example 4: Failover based on rule order - priority traffic +---------------------------------------------------------- + +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Overview +^^^^^^^^ +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Create rule order based configuration with low speed secondary link +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +.. code-block:: none + + delete load-balancing wan rule 20 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + set load-balancing wan rule 20 destination port sip + set load-balancing wan rule 20 protocol tcp + set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 + +Example 5: Exclude traffic from load balancing +---------------------------------------------- + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +.. image:: /_static/images/Wan_load_balancing_exclude1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Adding a rule for the second interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +.. code-block:: none + + set load-balancing wan rule 5 exclude + set load-balancing wan rule 5 inbound-interface eth+ + set load-balancing wan rule 5 destination address 10.0.0.0/8 + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/appendix/examples/zone-policy.rst b/docs/configexamples/zone-policy.rst index bfe77c2e..bfe77c2e 100644 --- a/docs/appendix/examples/zone-policy.rst +++ b/docs/configexamples/zone-policy.rst diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst deleted file mode 100644 index ee7f63a2..00000000 --- a/docs/configuration-overview.rst +++ /dev/null @@ -1,555 +0,0 @@ -.. _configuration-overview: - -###################### -Configuration Overview -###################### - -VyOS makes use of a unified configuration file for the entire system's -configuration: ``/config/config.boot``. This allows easy template -creation, backup, and replication of system configuration. A system can -thus also be easily cloned by simply copying the required configuration -files. - -Terminology -=========== - -A VyOS system has three major types of configurations: - -* **Active** or **Running** configuration is the system configuration - that is loaded and currently active (used by VyOS). Any change in - the configuration will have to be committed to belong to the - active/running configuration. - -* **Working** - is the configuration which is currently being modified - in configuration mode. Changes made to the working configuration do - not go into effect until the changes are committed with the - :cfgcmd:`commit` command. At which time the working configuration will - become the active or running configuration. - -* **Saved** - is a configuration saved to a file using the - :cfgcmd:`save` command. It allows you to keep safe a configuration for - future uses. There can be multiple configuration files. The default or - "boot" configuration is saved and loaded from the file - ``/config/config.boot``. - -Seeing and navigating the configuration -======================================= - -.. opcmd:: show configuration - - View the current active configuration, also known as the running - configuration, from the operational mode. - - .. code-block:: none - - vyos@vyos:~$ show configuration - interfaces { - ethernet eth0 { - address dhcp - hw-id 00:53:00:00:aa:01 - } - loopback lo { - } - } - service { - ssh { - port 22 - } - } - system { - config-management { - commit-revisions 20 - } - console { - device ttyS0 { - speed 9600 - } - } - login { - user vyos { - authentication { - encrypted-password **************** - } - level admin - } - } - ntp { - server 0.pool.ntp.org { - } - server 1.pool.ntp.org { - } - server 2.pool.ntp.org { - } - } - syslog { - global { - facility all { - level notice - } - facility protocols { - level debug - } - } - } - } - -By default, the configuration is displayed in a hierarchy like the above -example, this is only one of the possible ways to display the -configuration. When the configuration is generated and the device is -configured, changes are added through a collection of :cfgcmd:`set` and -:cfgcmd:`delete` commands. - -.. opcmd:: show configuration commands - - Get a collection of all the set commands required which led to the - running configuration. - - .. code-block:: none - - vyos@vyos:~$ show configuration commands - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' - set interfaces loopback 'lo' - set service ssh port '22' - set system config-management commit-revisions '20' - set system console device ttyS0 speed '9600' - set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' - set system login user vyos level 'admin' - set system ntp server '0.pool.ntp.org' - set system ntp server '1.pool.ntp.org' - set system ntp server '2.pool.ntp.org' - set system syslog global facility all level 'notice' - set system syslog global facility protocols level 'debug' - -Both these ``show`` commands should be executed when in operational -mode, they do not work directly in configuration mode. There is a -special way on how to :ref:`run_opmode_from_config_mode`. - -.. hint:: Use the ``show configuration commands | strip-private`` - command when you want to hide private data. You may want to do so if - you want to share your configuration on the `forum`_. - -.. _`forum`: https://forum.vyos.io - - -The config mode ---------------- - -When entering the configuration mode you are navigating inside a tree -structure, to enter configuration mode enter the command -:opcmd:`configure` when in operational mode. - -.. code-block:: none - - vyos@vyos$ configure - [edit] - vyos@vyos# - - -.. note:: When going into configuration mode, prompt changes from - ``$`` to ``#``. - - -All commands executed here are relative to the configuration level you -have entered. You can do everything from the top level, but commands -will be quite lengthy when manually typing them. - -The current hierarchy level can be changed by the :cfgcmd:`edit` -command. - -.. code-block:: none - - [edit] - vyos@vyos# edit interfaces ethernet eth0 - - [edit interfaces ethernet eth0] - vyos@vyos# - -You are now in a sublevel relative to ``interfaces ethernet eth0``, all -commands executed from this point on are relative to this sublevel. Use -eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top -of the hierarchy. You can also use the :cfgcmd:`up` command to move only -one level up at a time. - -.. cfgcmd:: show - -The :cfgcmd:`show` command within configuration mode will show the -working configuration indicating line changes with ``+`` for additions, -``>`` for replacements and ``-`` for deletions. - -**Example:** - -.. code-block:: none - - vyos@vyos:~$ configure - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - description MY_OLD_DESCRIPTION - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - [edit] - vyos@vyos# set interfaces ethernet eth0 address dhcp - [edit] - vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION - [edit] - vyos@vyos# delete interfaces ethernet eth0 disable - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - + address dhcp - > description MY_NEW_DESCRIPTION - - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - -It is also possible to display all `set` commands within configuration -mode using :cfgcmd:`show | commands` - -.. code-block:: none - - vyos@vyos# show interfaces ethernet eth0 | commands - set address dhcp - set hw-id 00:53:ad:44:3b:03 - -These commands are also relative to the level you are inside and only -relevant configuration blocks will be displayed when entering a -sub-level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# show - address dhcp - hw-id 00:53:ad:44:3b:03 - -Exiting from the configuration mode is done via the :cfgcmd:`exit` -command from the top level, executing :cfgcmd:`exit` from within a -sub-level takes you back to the top level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# exit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - -Comment -------- - -.. cfgcmd:: comment <config node> "comment text" - - Add comment as an annotation to a configuration node. - - The ``comment`` command allows you to insert a comment above the - ``<config node>`` configuration section. When shown, comments are - enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments - need to be commited, just like other config changes. - - To remove an existing comment from your current configuration, - specify an empty string enclosed in double quote marks (``""``) as - the comment text. - - Example: - - .. code-block:: none - - vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" - vyos@vyos# commit - vyos@vyos# show - firewall { - /* Yes I know this VyOS is cool */ - all-ping enable - broadcast-ping disable - ... - } - - .. note:: An important thing to note is that since the comment is - added on top of the section, it will not appear if the ``show - <section>`` command is used. With the above example, the `show - firewall` command would return starting after the ``firewall - {`` line, hiding the comment. - - - -Editing the configuration -========================= - -The configuration can be edited by the use of :cfgcmd:`set` and -:cfgcmd:`delete` commands from within configuration mode. Configuration -commands are flattened from the tree into 'one-liner' commands shown in -:opcmd:`show configuration commands` from operation mode. - -Commands are relative to the level where they are executed and all -redundant information from the current level is removed from the command -entered. - -.. code-block:: none - - [edit] - vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 - - [edit interfaces ethernet eth0] - vyos@vyos# set address 203.0.113.6/24 - -These two commands above are essentially the same, just executed from -different levels in the hierarchy. - -.. cfgcmd:: delete - - To delete a configuration entry use the :cfgcmd:`delete` command, - this also deletes all sub-levels under the current level you've - specified in the :cfgcmd:`delete` command. Deleting an entry will - also result in the element reverting back to its default value if one - exists. - - .. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# delete address 192.0.2.100/24 - -.. cfgcmd:: commit - - Any change you do on the configuration, will not take effect until - committed using the :cfgcmd:`commit` command in configuration mode. - - .. code-block:: none - - vyos@vyos# commit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ - -.. cfgcmd:: save - - In order to preserve configuration changes upon reboot, the - configuration must also be saved once applied. This is done using the - :cfgcmd:`save` command in configuration mode. - - .. code-block:: none - - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done - - .. code-block:: none - - vyos@vyos# save [tab] - Possible completions: - <Enter> Save to system config file - <file> Save to file on local machine - scp://<user>:<passwd>@<host>/<file> Save to file on remote machine - ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine - tftp://<host>/<file> Save to file on remote machine - vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot - Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... - ######################################################################## 100.0% - Done - -.. cfgcmd:: exit [discard] - - Configuration mode can not be exited while uncommitted changes exist. - To exit configuration mode without applying changes, the - :cfgcmd:`exit discard` command must be used. - - All changes in the working config will thus be lost. - - .. code-block:: none - - vyos@vyos# exit - Cannot exit: configuration modified. - Use 'exit discard' to discard the changes and exit. - [edit] - vyos@vyos# exit discard - -.. _run_opmode_from_config_mode: - -Access opmode from config mode -============================== - -When inside configuration mode you are not directly able to execute -operational commands. - -.. cfgcmd:: run - - Access to these commands are possible through the use of the - ``run [command]`` command. From this command you will have access to - everything accessible from operational mode. - - Command completion and syntax help with ``?`` and ``[tab]`` will also - work. - - .. code-block:: none - - [edit] - vyos@vyos# run show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 0.0.0.0/0 u/u - -Managing configurations -======================= - -VyOS comes with an integrated versioning system for the system -configuration. It automatically maintains a backup of every previous -configuration which has been committed to the system. The configurations -are versioned locally for rollback but they can also be stored on a -remote host for archiving/backup reasons. - -Local Archive -------------- - -Revisions are stored on disk. You can view, compare and rollback them to -any previous revisions if something goes wrong. - -.. opcmd:: show system commit - - View all existing revisions on the local system. - - .. code-block:: none - - vyos@vyos:~$ show system commit - 0 2015-03-30 08:53:03 by vyos via cli - 1 2015-03-30 08:52:20 by vyos via cli - 2 2015-03-26 21:26:01 by root via boot-config-loader - 3 2015-03-26 20:43:18 by root via boot-config-loader - 4 2015-03-25 11:06:14 by root via boot-config-loader - 5 2015-03-25 01:04:28 by root via boot-config-loader - 6 2015-03-25 00:16:47 by vyos via cli - 7 2015-03-24 23:43:45 by root via boot-config-loader - -.. cfgcmd:: compare <saved | N> <M> - - Compare difference in configuration revisions. - - .. code-block:: none - - vyos@vyos# compare [tab] - Possible completions: - <Enter> Compare working & active configurations - saved Compare working & saved configurations - <N> Compare working with revision N - <N> <M> Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - - Revisions can be compared with :cfgcmd:`compare N M` command, where N - and M are revision numbers. The output will describe how the - configuration N is when compared to YM indicating with a plus sign - (``+``) the additional parts N has when compared to M, and indicating - with a minus sign (``-``) the lacking parts N misses when compared to - Y. - - .. code-block:: none - - vyos@vyos# compare 0 6 - [edit interfaces] - +dummy dum1 { - + address 10.189.0.1/31 - +} - [edit interfaces ethernet eth0] - +vif 99 { - + address 10.199.0.1/31 - +} - -vif 900 { - - address 192.0.2.4/24 - -} - -.. cfgcmd:: set system config-management commit-revisions <N> - - You can specify the number of revisions stored on disk. N can be in - the range of 0 - 65535. When the number of revisions exceeds the - configured value, the oldest revision is removed. The default setting - for this value is to store 20 revisions locally. - -Rollback Changes ----------------- - -You can rollback configuration changes using the rollback command. This -willn apply the selected revision and trigger a system reboot. - -.. cfgcmd:: rollback <N> - - Rollback to revision N (currently requires reboot) - - .. code-block:: none - - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! - -Remote Archive --------------- - -VyOS can upload the configuration to a remote location after each call -to :cfgcmd:`commit`. You will have to set the commit-archive location. -TFTP, FTP, SCP and SFTP servers are supported. Every time a -:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied -to the defined destination(s). The filename used on the remote host will -be ``config.boot-hostname.YYYYMMDD_HHMMSS``. - -.. cfgcmd:: set system config-management commit-archive location <URI> - - Specify remote location of commit archive as any of the below - :abbr:`URI (Uniform Resource Identifier)` - - * ``scp://<user>:<passwd>@<host>/<dir>`` - * ``sftp://<user>:<passwd>@<host>/<dir>`` - * ``ftp://<user>:<passwd>@<host>/<dir>`` - * ``tftp://<host>/<dir>`` - -.. note:: The number of revisions don't affect the commit-archive. - -.. note:: You may find VyOS not allowing the secure connection because - it cannot verify the legitimacy of the remote server. You can use - the workaround below to quickly add the remote host's SSH - fingerprint to your ``~/.ssh/known_hosts`` file: - - .. code-block:: none - - vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts - -Restore Default ---------------- - -In the case you want to completely delete your configuration and restore -the default one, you can enter the following command in configuration -mode: - -.. code-block:: none - - load /opt/vyatta/etc/config.boot.default - -You will be asked if you want to continue. If you accept, you will have -to use :cfgcmd:`commit` if you want to make the changes active. - -Then you may want to :cfgcmd:`save` in order to delete the saved -configuration too. - -.. note:: If you are remotely connected, you will lose your connection. - You may want to copy first the config, edit it to ensure - connectivity, and load the edited config. diff --git a/docs/firewall.rst b/docs/configuration/firewall/index.rst index 2d9001a6..04800b91 100644 --- a/docs/firewall.rst +++ b/docs/configuration/firewall/index.rst @@ -1,10 +1,12 @@ .. _firewall: +######## Firewall -======== +######## +******** Overview --------- +******** VyOS makes use of Linux `netfilter <https://netfilter.org/>`_ for packet filtering. @@ -23,8 +25,9 @@ or zone based firewall policy. 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. @@ -139,8 +142,9 @@ Some firewall settings are global and have a affect on the whole system. 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 @@ -157,7 +161,7 @@ names. Address Groups -************** +============== In a **address group** a single IP adresses or IP address ranges are definded. @@ -181,7 +185,7 @@ definded. 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 @@ -206,7 +210,7 @@ recommended. 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 @@ -231,8 +235,9 @@ filtering unnecessary ports. Ranges of ports can be specified by using 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 @@ -280,7 +285,7 @@ the action of the rule will executed. 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. @@ -412,8 +417,9 @@ There are a lot of matching criteria gainst which the package can be tested. Match against the state of a packet. +*********************************** Applying a Rule-Set to an Interface ------------------------------------ +*********************************** A Rule-Set can be appliend to every inteface: @@ -438,8 +444,9 @@ A Rule-Set can be appliend to every inteface: 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 @@ -452,7 +459,7 @@ 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. @@ -476,7 +483,7 @@ To define a zone setup either one with interfaces or a local zone. 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. @@ -495,11 +502,12 @@ first. set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 +*********************** Operation-mode Firewall ------------------------ +*********************** Rule-set overview -***************** +================= .. opcmd:: show firewall @@ -571,7 +579,7 @@ Rule-set overview This will show you a summary about rule-sets and groups - .. code-block:: + .. code-block:: none vyos@vyos:~$ show firewall summary @@ -662,7 +670,7 @@ Rule-set overview Zone-Policy Overview -******************** +==================== .. opcmd:: show zone-policy zone <name> @@ -683,7 +691,7 @@ Zone-Policy Overview Show Firewall log -***************** +================= .. opcmd:: show log firewall [name | ipv6name] <name> @@ -697,7 +705,7 @@ Show Firewall log Example Partial Config ----------------------- +====================== .. code-block:: none @@ -765,3 +773,75 @@ Example Partial Config } } } + + +.. _routing-mss-clamp: + + +**************** +TCP-MSS Clamping +**************** + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. + +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. + + +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + + + +IPv4 +==== + + +.. cfgcmd:: set firewall options interface <interface> adjust-mss + <number-of-bytes> + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` +for your WireGuard `wg02` tunnel. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss '1452' + set firewall options interface wg02 adjust-mss '1372' + + + +IPv6 +==== + +.. cfgcmd:: set firewall options interface <interface> adjust-mss6 + <number-of-bytes> + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and +`wg02` interface. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss6 '1280' + set firewall options interface wg02 adjust-mss6 '1280' + + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. diff --git a/docs/high-availability.rst b/docs/configuration/highavailability/index.rst index ad714597..a223c283 100644 --- a/docs/high-availability.rst +++ b/docs/configuration/highavailability/index.rst @@ -3,21 +3,29 @@ 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. +VRRP (Virtual Router 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. +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 @@ -27,7 +35,8 @@ minimal config 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: +You can verify your VRRP group status with the operational mode +``run show vrrp`` command: .. code-block:: none @@ -39,7 +48,9 @@ You can verify your VRRP group status with the operational mode ``run show vrrp` 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. +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 ---------------------- @@ -50,7 +61,9 @@ You can disable a VRRP group with ``disable`` option: 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. +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 --------------------------- @@ -61,7 +74,8 @@ VRRP priority can be set with ``priority`` option: 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. +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. Sync groups ----------- @@ -98,21 +112,29 @@ In the following example, when VLAN9 transitions, VLAN20 will also transition: } -.. 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. +.. 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. +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: +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: +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 @@ -121,7 +143,9 @@ You can also configure the time interval for preemption with the "preempt-delay" 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. +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 @@ -131,13 +155,19 @@ By default VRRP uses multicast packets. If your network does not support multica 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. +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: +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 @@ -148,8 +178,11 @@ This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.s 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: +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 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/interfaces/bond.rst b/docs/configuration/interfaces/bonding.rst index 74089f96..bf7cfc2c 100644 --- a/docs/interfaces/bond.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -10,72 +10,35 @@ 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 -############# +************* -Address -------- +Common interface configuration +============================== -.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6> +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 - Configure interface `<interface>` with one or more interface addresses. - - * **address** can be specified multiple times as IPv4 and/or IPv6 address, - e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - * **dhcp** interface address is received by DHCP from a DHCP server on this - segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on - this segment. - - Example: - - .. code-block:: none - - set interfaces bonding bond0 address 192.0.2.1/24 - set interfaces bonding bond0 address 192.0.2.2/24 - set interfaces bonding bond0 address 2001:db8::ffff/64 - set interfaces bonding bond0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bonding <interface> ipv6 address eui64 <prefix> - - :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in - :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. - - .. code-block:: none - - set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64 - - -Link Administration -------------------- - -.. cfgcmd:: set interfaces bonding <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - - -.. cfgcmd:: set interfaces bonding <interface> disable +Member Interfaces +================= - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. +.. cfgcmd:: set interfaces bonding <interface> member interface <member> -.. cfgcmd:: set interfaces bonding <interface> mac <mac-address> + Enslave `<member>` interface to bond `<interface>`. - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. +Bond options +============ -.. cfgcmd:: set interfaces bonding <interface> mode <mode> +.. cfgcmd:: set interfaces bonding <interface> 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 + * ``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. @@ -87,7 +50,7 @@ Link Administration 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-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. @@ -102,24 +65,24 @@ Link Administration 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 + * ``broadcast`` - Broadcast policy: transmits everything on all slave interfaces. This mode provides fault tolerance. - * **round-robin** - Round-robin policy: Transmit packets in sequential + * ``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 + * ``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 + * ``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 @@ -151,7 +114,7 @@ Link Administration 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 + * ``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` @@ -159,6 +122,25 @@ Link Administration This mode provides load balancing and fault tolerance. +.. cfgcmd:: set interfaces bonding <interface> 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 <interface> hash-policy <policy> * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field @@ -274,15 +256,31 @@ Link Administration The maximum number of targets that can be specified is 16. The default value is no IP addresses. -Member Interfaces ------------------ +Offloading +---------- -.. cfgcmd:: set interfaces bonding <interface> member interface <member> +.. cmdinclude:: /_include/interface-xdp.txt + :var0: bonding + :var1: bond0 - Enslave `<member>` interface to bond `<interface>`. +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bond + :var1: bond0 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bonding + :var1: bond1 + :var2: eth3 + +******* Example -------- +******* The following configuration on VyOS applies to all following 3rd party vendors. It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with @@ -303,7 +301,7 @@ a per VIF IPv4 address. set interfaces bonding bond0 member interface eth2 Cisco Catalyst -^^^^^^^^^^^^^^ +============== Assign member interfaces to PortChannel @@ -333,7 +331,7 @@ allowed VLAN interfaces, STP will happen here. Juniper EX Switch -^^^^^^^^^^^^^^^^^ +================= For a headstart you can use the below example on how to build a bond with two interfaces from VyOS to a Juniper EX Switch system. @@ -362,10 +360,10 @@ interfaces from VyOS to a Juniper EX Switch system. set interfaces xe-1/1/0 ether-options 802.3ad ae0 Aruba/HP -^^^^^^^^ +======== -For a headstart you can use the below example on how to build a bond,port-channel -with two interfaces from VyOS to a Aruba/HP 2510G switch. +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. .. code-block:: none @@ -376,15 +374,202 @@ with two interfaces from VyOS to a Aruba/HP 2510G switch. vlan 10 tagged Trk1 vlan 100 tagged Trk1 +Arista EOS +========== + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +.. figure:: /_static/images/vyos_arista_bond_lacp.png + :alt: VyOS Arista EOS setup + +**R1** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } + +**R2** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } + +**SW1** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +**SW2** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +.. note:: When using EVE-NG to lab this environment ensure you are using e1000 + as the desired driver for your VyOS network interfaces. When using the regular + virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel + will never become active! + +********* Operation -######### +********* -.. code-block:: none +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net + + +.. opcmd:: show interfaces bonding <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 + +.. opcmd:: show interfaces bonding <interface> detail + + Show detailed information about the underlaying physical links on given + bond `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 - vyos@vyos:~$ show interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net diff --git a/docs/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index a7343a0d..7f49f9a8 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -14,98 +14,19 @@ standard. .. note:: Spanning Tree Protocol is not enabled by default in VyOS. :ref:`stp` can be easily enabled if needed. +************* Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | - dhcpv6> - - Configure interface `<interface>` with one or more interface - addresses. - - * **address** can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - * **dhcp** interface address is received by DHCP from a DHCP server - on this segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 - server on this segment. - - Example: - - .. code-block:: none - - set interfaces bridge br0 address 192.0.2.1/24 - set interfaces bridge br0 address 192.0.2.2/24 - set interfaces bridge br0 address 2001:db8::ffff/64 - set interfaces bridge br0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bridge <interface> ipv6 address eui64 - <prefix> - - :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in - :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 - address. - - .. code-block:: none - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - - -.. cfgcmd:: set interfaces bridge <interface> aging <time> - - MAC address aging `<time`> in seconds (default: 300). - - -.. cfgcmd:: set interfaces bridge <interface> max-age <time> - - Bridge maximum aging `<time>` in seconds (default: 20). - - If a another bridge in the spanning tree does not send out a hello - packet for a long period of time, it is assumed to be dead. - - -Link Administration -------------------- - -.. cfgcmd:: set interfaces bridge <interface> description <description> - - Assign given `<description>` to interface. Description will also be - passed to SNMP monitoring systems. - - -.. cfgcmd:: set interfaces bridge <interface> disable - - Disable given `<interface>`. It will be placed in administratively - down (``A/D``) state. - - -.. cfgcmd:: set interfaces bridge <interface> disable-flow-control - - Disable Ethernet flow control (pause frames). - - -.. cfgcmd:: set interfaces bridge <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on - given `<interface>`. - - -.. cfgcmd:: set interfaces bridge <interface> igmp querier - - Enable IGMP querier +************* +Common interface configuration +============================== +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 Member Interfaces ------------------ +================= .. cfgcmd:: set interfaces bridge <interface> member interface <member> @@ -139,6 +60,23 @@ Member Interfaces deciding which link to use. Faster interfaces should have lower costs. +Bridge Options +============== + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier .. _stp: @@ -175,9 +113,75 @@ links providing fault tolerance if an active link fails. Designated Bridges. Hello packets are used to communicate information about the topology throughout the entire Bridged Local Area Network. +VLAN +==== + +Enable VLAN-Aware Bridge +------------------------ + +.. cfgcmd:: set interfaces bridge <interface> enable-vlan + + To activate the VLAN aware bridge, you must activate this setting to use VLAN + settings for the bridge + +VLAN Options +------------ + +.. note:: It is not valid to use the `vif 1` option for VLAN aware bridges + because VLAN aware bridges assume that all unlabeled packets belong to + the default VLAN 1 member and that the VLAN ID of the bridge's parent + interface is always 1 + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bridge + :var1: br0 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + native-vlan <vlan-id> + + Set the native VLAN ID flag of the interface. When a data packet without a + VLAN tag enters the port, the data packet will be forced to add a tag of a + specific vlan id. When the vlan id flag flows out, the tag of the vlan id + will be stripped + + Example: Set `eth0` member port to be native VLAN 2 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 native-vlan 2 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + allowed-vlan <vlan-id> + + Allows specific VLAN IDs to pass through the bridge member interface. This + can either be an individual VLAN id or a range of VLAN ids delimited by a + hyphen. + + Example: Set `eth0` member port to be allowed VLAN 4 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 4 + + Example: Set `eth0` member port to be allowed VLAN 6-8 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bridge + :var1: br1 + :var2: eth3 -Example -------- +******** +Examples +******** + +Create a basic bridge +===================== Creating a bridge interface is very simple. In this example we will have: @@ -211,8 +215,49 @@ This results in the active configuration: stp -Operation -========= +Using VLAN aware Bridge +======================= + +An example of creating a VLAN-aware bridge is as follows: + +* A bridge named `br100` +* The member interface `eth1` is a trunk that allows VLAN 10 to pass +* VLAN 10 on member interface `eth2` (ACCESS mode) +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 enable-vlan + set interfaces bridge br100 member interface eth1 allowed-vlan 10 + set interfaces bridge br100 member interface eth2 native-vlan 10 + set interfaces bridge br100 vif 10 address 192.0.2.1/24 + set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } + + +Using the operation mode command to view Bridge Information +=========================================================== .. opcmd:: show bridge diff --git a/docs/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index e452ae73..c9845230 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst @@ -18,43 +18,32 @@ you can have as many as you want. destination. A :ref:`dummy-interface` Interface should always be preferred over a :ref:`loopback-interface` interface. - +************* Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6> - - Configure dummy interface `<interface>` with one or more interface - addresses. Address can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - - Example: - - .. code-block:: none - - set interfaces dummy dum10 address 192.0.2.1/24 - set interfaces dummy dum10 address 192.0.2.2/24 - set interfaces dummy dum10 address 2001:db8::ffff/64 - set interfaces dummy dum10 address 2001:db8:100::ffff/64 +************* -Link Administration -------------------- +Common interface configuration +============================== -.. cfgcmd:: set interfaces dummy <interface> description <description> +.. cmdinclude:: /_include/interface-address.txt + :var0: dummy + :var1: dum0 - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. +.. cmdinclude:: /_include/interface-description.txt + :var0: dummy + :var1: dum0 -.. cfgcmd:: set interfaces dummy <interface> disable +.. cmdinclude:: /_include/interface-disable.txt + :var0: dummy + :var1: dum0 - Disable given `<interface>`. It will be placed in administratively down - state. +.. cmdinclude:: /_include/interface-vrf.txt + :var0: dummy + :var1: dum0 +********* Operation -========= +********* .. opcmd:: show interfaces dummy diff --git a/docs/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 0633ad2c..1d99019c 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -4,40 +4,22 @@ Ethernet ######## -Configuration -############# - -Address -------- - -.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6> - - .. include:: common-ip-ipv6-addr.txt - - Example: - - .. code-block:: none - - set interfaces ethernet eth0 address 192.0.2.1/24 - set interfaces ethernet eth0 address 192.0.2.2/24 - set interfaces ethernet eth0 address 2001:db8::ffff/64 - set interfaces ethernet eth0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf +This will be the most widely used interface on a router carrying traffic to the +real world. - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces ethernet <interface> ipv6 address eui64 <prefix> - - :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in - :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. +************* +Configuration +************* - .. code-block:: none +Common interface configuration +============================== - set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64 +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 -Speed/Duplex ------------- +Ethernet options +================ .. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> @@ -49,7 +31,8 @@ Speed/Duplex VyOS default will be `auto`. -.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | + 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> Configure physical interface speed setting. @@ -67,36 +50,101 @@ Speed/Duplex VyOS default will be `auto`. -Link Administration -------------------- -.. cfgcmd:: set interfaces ethernet <interface> description <description> +.. cfgcmd:: set interfaces ethernet <interface> mirror <interface> + + Use this command to mirror the inbound traffic from one Ethernet interface to + another interface. This feature is typically used to provide a copy of traffic + inbound on one interface to a system running a monitoring or IPS application + on another interface. The benefit of mirroring the traffic is that the + application is isolated from the source traffic and so application processing + does not affect the traffic or the system performance. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 mirror eth1 - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. +Offloading +---------- -.. cfgcmd:: set interfaces ethernet <interface> disable +.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | sg | tso | + ufo | rps> - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. + Enable different types of hardware offloading on the given NIC. -.. cfgcmd:: set interfaces ethernet <interface> disable-flow-control + :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is + meant to deal with cases where device drivers cannot perform the offloads + described above. What occurs in GSO is that a given skbuff will have its data + broken out over multiple skbuffs that have been resized to match the MSS + provided via skb_shinfo()->gso_size. - Disable Ethernet flow control (pause frames). + Before enabling any hardware segmentation offload a corresponding software + offload is required in GSO. Otherwise it becomes possible for a frame to be + re-routed between devices and end up being unable to be transmitted. + :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any + frame assembled by GRO should be segmented to create an identical sequence of + frames using GSO, and any sequence of frames segmented by GSO should be able + to be reassembled back to the original by GRO. The only exception to this is + IPv4 ID in the case that the DF bit is set for a given IP header. If the + value of the IPv4 ID is not sequentially incrementing it will be altered so + that it is when a frame assembled via GRO is segmented via GSO. -.. cfgcmd:: set interfaces ethernet <interface> mac <mac-address> + :abbr:`RPS (Receive Packet Steering)` is logically a software implementation + of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily + called later in the datapath. Whereas RSS selects the queue and hence CPU that + will run the hardware interrupt handler, RPS selects the CPU to perform + protocol processing above the interrupt handler. This is accomplished by + placing the packet on the desired CPU's backlog queue and waking up the CPU + for processing. RPS has some advantages over RSS: - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. + - it can be used with any NIC, + - software filters can easily be added to hash over new protocols, + - it does not increase hardware device interrupt rate (although it does + introduce inter-processor interrupts (IPIs)). -.. cfgcmd:: set interfaces ethernet <interface> mtu <mtu> - Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It - is the size (in bytes) of the largest ethernet frame sent on this link. +.. cmdinclude:: /_include/interface-xdp.txt + :var0: ethernet + :var1: eth0 +Authentication (EAPoL) +---------------------- + +.. cmdinclude:: /_include/interface-eapol.txt + :var0: ethernet + :var1: eth0 + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + :var1: eth1 + :var2: eth3 + +********* Operation -========= +********* .. opcmd:: show interfaces ethernet @@ -129,6 +177,8 @@ Operation TX: bytes packets errors dropped carrier collisions 5601460 62595 0 0 0 0 +.. stop_vyoslinter + .. opcmd:: show interfaces ethernet <interface> physical Show information about physical `<interface>` @@ -168,6 +218,8 @@ Operation supports-register-dump: yes supports-priv-flags: no +.. start_vyoslinter + .. opcmd:: show interfaces ethernet <interface> physical offload Show available offloading functions on given `<interface>` @@ -235,3 +287,29 @@ Operation Vendor SN : FNS092xxxxx Date code : 0506xx +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> xdp + + Display XDP forwarding statistics + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth1 xdp + + Collecting stats from BPF map + - BPF map (bpf_map_type:6) id:176 name:xdp_stats_map key_size:4 value_size:16 max_entries:5 + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250340 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250317 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250314 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000410 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + diff --git a/docs/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index a4bc22aa..9e00d621 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -32,24 +32,19 @@ Geneve Header: | Variable Length Options | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +************* Configuration -============= +************* -.. cfgcmd:: set interfaces geneve gnv0 address <address> +Common interface configuration +============================== - Configure interface `<interface>` with one or more interface addresses. +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: geneve + :var1: gnv0 - **address** can be specified multiple times as IPv4 and/or IPv6 address, - e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - - Example: - - .. code-block:: none - - set interfaces geneve gnv0 address 192.0.2.1/24 - set interfaces geneve gnv0 address 192.0.2.2/24 - set interfaces geneve gnv0 address 2001:db8::ffff/64 - set interfaces geneve gnv0 address 2001:db8:100::ffff/64 +GENEVE options +============== .. cfgcmd:: set interfaces geneve gnv0 remote <address> @@ -64,7 +59,3 @@ Configuration decisions or MAY be used as a mechanism to distinguish between overlapping address spaces contained in the encapsulated packet when load balancing across CPUs. - -.. cfgcmd:: set interfaces geneve gnv0 mtu <mtu> - - Set interface :abbr:`MTU (Maximum Transfer Unit)` size. diff --git a/docs/interfaces/advanced-index.rst b/docs/configuration/interfaces/index.rst index c666f7ae..85d2c177 100644 --- a/docs/interfaces/advanced-index.rst +++ b/docs/configuration/interfaces/index.rst @@ -1,22 +1,28 @@ -.. _advanced_network-interfaces: +########## +Interfaces +########## -########################### -Advanced Network Interfaces -########################### .. toctree:: :maxdepth: 1 + :includehidden: - bond + bonding bridge dummy + ethernet geneve l2tpv3 + loopback macsec + openvpn + pppoe pseudo-ethernet - qinq tunnel - vlan + vti vxlan + wireguard wireless wirelessmodem + + diff --git a/docs/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index ea540c01..a4b7be36 100644 --- a/docs/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -1,18 +1,90 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _l2tpv3-interface: +###### L2TPv3 ------- +###### -L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_ -or in :rfc:`3921` +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to :ref:`mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements. -L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited -to PPP. +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in :rfc:`3921`. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 + +L2TPv3 options +============== + +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP + +.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address> + + set the IP address of the local interface to be used for the tunnel. + + This address must be the address of a local interface. May be specified as an + IPv4 address or an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address> + + Set the IP address of the remote peer. May be specified as an IPv4 address or + an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + Set the peer session id, which is a 32-bit integer value assigned to the + session by the peer. The value used must match the session_id value being + used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +******* +Example +******* Over IP -^^^^^^^ +======= .. code-block:: none @@ -31,7 +103,7 @@ Over IP Inverse configuration has to be applied to the remote side. Over UDP -^^^^^^^^ +======== UDP mode works better with NAT: @@ -58,7 +130,7 @@ To create more than one tunnel, use distinct UDP ports. Over IPSec, L2 VPN (bridge) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +=========================== This is the LAN extension use case. The eth0 port of the distant VPN peers will be directly connected like if there was a switch between them. @@ -118,5 +190,3 @@ L2TPv3: set interfaces l2tpv3 l2tpeth0 session-id '110' set interfaces l2tpv3 l2tpeth0 source-port '5000' set interfaces l2tpv3 l2tpeth0 tunnel-id '10' - -.. _`Wikipedia L2TPv3`: https://en.wikipedia.org/wiki/L2TPv3 diff --git a/docs/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index e15062cf..f7386c62 100644 --- a/docs/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -19,28 +19,24 @@ services on your local machine. destination. A :ref:`dummy-interface` Interface should always be preferred over a :ref:`loopback-interface` interface. +************* Configuration -============= +************* -Address -------- +Common interface configuration +============================== -.. cfgcmd:: set interfaces loopback lo address <address> +.. cmdinclude:: /_include/interface-address.txt + :var0: loopback + :var1: lo - Configure Loopback interface `lo` with one or more interface addresses. - Address can be specified multiple times as IPv4 and/or IPv6 address, e.g. - 192.0.2.1/24 and/or 2001:db8::1/64. - -Link Administration -------------------- - -.. cfgcmd:: set interfaces loopback lo description <description> - - Assign given `<description>` to interface `lo`. Description will also be - passed to SNMP monitoring systems. +.. cmdinclude:: /_include/interface-description.txt + :var0: loopback + :var1: lo +********* Operation -========= +********* .. opcmd:: show interfaces loopback diff --git a/docs/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst index d7af0c16..2bf643aa 100644 --- a/docs/interfaces/macsec.rst +++ b/docs/configuration/interfaces/macsec.rst @@ -13,8 +13,19 @@ including DHCP or ARP requests. It does not compete with other security solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are used for their own specific use cases. +************* Configuration -############# +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 + +MACsec options +============== .. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] @@ -34,7 +45,6 @@ Configuration A physical interface is required to connect this MACsec instance to. Traffic leaving this interfac will now be authenticated/encrypted. - Key Management -------------- @@ -67,8 +77,9 @@ Replay protection - ``0``: No replay window, strict check - ``1-4294967295``: Number of packets that could be misordered +********* Operation -========= +********* .. opcmd:: run generate macsec mka-cak @@ -114,8 +125,9 @@ Operation cipher suite: GCM-AES-128, using ICV length 16 TXSC: 005056bfefaa0001 on SA 0 +******** Examples -======== +******** * Two routers connected both via eth1 through an untrusted switch * R1 has 192.0.2.1/24 & 2001:db8::1/64 diff --git a/docs/vpn/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 159366dc..8b32743f 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -159,13 +159,13 @@ Local Configuration: .. code-block:: none - set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1 + set protocols static route 10.1.0.0/16 interface vtun1 Remote Configuration: .. code-block:: none - set protocols static interface-route 10.0.0.0/16 next-hop-interface vtun1 + set protocols static route 10.0.0.0/16 interface vtun1 Firewall policy can also be applied to the tunnel interface for `local`, `in`, and `out` directions and function identically to ethernet interfaces. @@ -186,7 +186,8 @@ Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. Refer this section **Generate X.509 Certificate and Keys** to generate a CA certificate, a server certificate and key, a certificate revocation list, a Diffie-Hellman -key exchange parameters file. You do not need client certificates and keys for the server setup. +key exchange parameters file. You do not need client certificates and keys for +the server setup. In this example we will use the most complicated case: a setup where each client is a router that has its own subnet (think HQ and branch offices), since @@ -252,10 +253,10 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: .. code-block:: none - set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 + set protocols static route 10.23.0.0/20 interface vtun10 Generate X.509 Certificate and Keys -*********************************** +----------------------------------- OpenVPN ships with a set of scripts called Easy-RSA that can generate the appropriate files needed for an OpenVPN setup using X.509 certificates. @@ -269,16 +270,16 @@ Copy the Easy-RSA scripts to a new directory to modify the values. cd /config/my-easy-rsa-config To ensure the consistent use of values when generating the PKI, set default -values to be used by the PKI generating scripts. Rename the vars.example filename -to vars +values to be used by the PKI generating scripts. Rename the vars.example +filename to vars .. code-block:: none mv vars.example vars -Following is the instance of the file after editing. You may also change other values in -the file at your discretion/need, though for most cases the defaults should be just fine. -(do not leave any of these parameters blank) +Following is the instance of the file after editing. You may also change other +values in the file at your discretion/need, though for most cases the defaults +should be just fine. (do not leave any of these parameters blank) .. code-block:: none @@ -292,9 +293,9 @@ the file at your discretion/need, though for most cases the defaults should be j set_var EASYRSA_KEY_SIZE 2048 -init-pki option will create a new pki directory or will delete any previously generated -certificates stored in that folder. The term 'central' is used to refer server and -'branch' for client +init-pki option will create a new pki directory or will delete any previously +generated certificates stored in that folder. The term 'central' is used to +refer server and 'branch' for client .. note:: Remember the “CA Key Passphrase” prompted in build-ca command, as it will be asked in signing the server/client certificate. @@ -308,48 +309,50 @@ certificates stored in that folder. The term 'central' is used to refer server a vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass -To generate a certificate revocation list for any client, execute these commands: +To generate a certificate revocation list for any client, execute these +commands: .. code-block:: none vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1 vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl -Copy the files to /config/auth/ovpn/ to use in OpenVPN tunnel creation +Copy the files to /config/auth/openvpn/ to use in OpenVPN tunnel creation .. code-block:: none - vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/openvpn -Additionally, each client needs a copy of ca.crt and its own client key and cert files. -The files are plaintext so they may be copied either manually, +Additionally, each client needs a copy of ca.crt and its own client key and +cert files. The files are plaintext so they may be copied either manually, or through a remote file transfer tool like scp. Whichever method you use, the files need to end up in the proper location on each router. For example, Branch 1's router might have the following files: .. code-block:: none - vyos@branch1-rtr:$ ls /config/auth/ovpn + vyos@branch1-rtr:$ ls /config/auth/openvpn ca.crt branch1.crt branch1.key Client Authentication ---------------------- +===================== LDAP -**** +---- Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employees. VyOS and OpenVPN support using -LDAP/AD as single user backend. +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is -shipped with every VyOS installation. A dedicated configuration file is required. -It is best practise to store it in ``/config`` to survive image updates +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in ``/config`` to survive image +updates .. code-block:: none @@ -380,7 +383,7 @@ The required config file may look like: </Authorization> Active Directory -**************** +^^^^^^^^^^^^^^^^ Despite the fact that AD is a superset of LDAP @@ -435,7 +438,8 @@ If you only want to check if the user account is enabled and can authenticate RequireGroup false </Authorization> -A complete LDAP auth OpenVPN configuration could look like the following example: +A complete LDAP auth OpenVPN configuration could look like the following +example: .. code-block:: none @@ -453,8 +457,8 @@ A complete LDAP auth OpenVPN configuration could look like the following example server { domain-name example.com max-connections 5 - name-server 1.1.1.1 - name-server 9.9.9.9 + name-server 203.0.113.0.10 + name-server 198.51.100.3 subnet 172.18.100.128/29 } tls { @@ -534,7 +538,8 @@ Will add ``persistent-key`` at the end of the generated OpenVPN configuration. Please use this only as last resort - things might break and OpenVPN won't start if you pass invalid options/syntax. -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'push "keepalive 1 10"' +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'push "keepalive 1 10"' Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. @@ -542,4 +547,44 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. -.. include:: ../common-references.rst + +Troubleshooting +=============== + +VyOS provides some operational commands on OpenVPN. + +Check status +------------ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. + +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. + +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site + interfaces. + + +Reset OpenVPN +------------- + +The following commands let you reset OpenVPN. + +.. opcmd:: reset openvpn client <text> + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface <interface> + + Uset this command to reset the OpenVPN process on a specific interface. + + + +.. include:: /_include/common-references.txt diff --git a/docs/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index ae6b11cc..1bbccc0c 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -14,15 +14,16 @@ encryption, and compression." Typical use of PPPoE involves leveraging the PPP facilities for authenticating the user with a username and password, predominately via the PAP protocol and less often via CHAP. +*************** Operating Modes -=============== +*************** VyOS supports setting up PPPoE in two different ways to a PPPoE internet connection. This is due to most ISPs provide a modem that is also a wireless router. Home Users ----------- +========== In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an :rfc:`1918` @@ -35,7 +36,7 @@ few extra layers of complexity, particularly if you use some NAT or tunnel features. Business Users --------------- +============== In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control @@ -51,7 +52,26 @@ configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. +************* Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 + +PPPoE options ============= .. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> @@ -79,7 +99,7 @@ Configuration .. cfgcmd:: set interfaces pppoe <interface> connect-on-demand - Enables or disables on-demand PPPoE connection on a PPPoE unit. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPPoE connections automatically once traffic passes through the interface. A disabled on-demand @@ -93,7 +113,7 @@ Configuration timeout period, after which an idle PPPoE link will be disconnected. A non-zero idle timeout will never disconnect the link after it first came up. -.. cfgcmd:: set interfaces pppoe <interface> default-route +.. cfgcmd:: set interfaces pppoe <interface> default-route [auto | force | none] Use this command to specify whether to automatically add a default route pointing to the endpoint of the PPPoE when the link comes up. The default @@ -102,15 +122,15 @@ Configuration **default:** A default route to the remote endpoint is automatically added when the link comes up (i.e. auto). -.. cfgcmd:: set interfaces pppoe <interface> description - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. + * auto: A default route is added if no other default route (From any + source) already exists. + * force: A default route is added after removing *all* existing default + routes. + * none: No default route is installed. -.. cfgcmd:: set interfaces pppoe <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. +.. note:: In all modes except 'none', all default routes using this interface + will be removed when the interface is torn down - even manually installed + static routes. .. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> @@ -158,55 +178,18 @@ Configuration IPv6 ---- -.. cfgcmd:: set interfaces pppoe <interface> ipv6 enable - - Use this command to enable IPv6 support on this PPPoE connection. - .. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf Use this command to enable acquisition of IPv6 address using stateless autoconfig (SLAAC). -Prefix Delegation (DHCPv6-PD) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS 1.3 (equuleus) supports DHCPv6-PD. DHCPv6 Prefix Delegation is supported -by most ISPs who provide native IPv6 for consumers on fixed networks. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> length <length> - - Some ISPs by default only delegate a /64 prefix. To request for a specific - prefix size use this option to request for a bigger delegation for this pd - `<id>`. This value - is in the range from 32 - 64 so you could request up to /32 down to a /64 - delegation. - - Default value is 64. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> interface <prefix-interface> address <local-addr> - - This statement specifies the interface address used locally on the interfcae - where the prefix has been delegated to. ID must be a decimal integer. - It will be combined with the delegated prefix and the sla-id to form a - complete interface address. The default is to use the EUI-64 address of the - interface. - - Example: - - Using `<id>` value 65535 will assign IPv6 address <prefix>::ffff to the - interface. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> interface <prefix-interface> sla-id <id> - - This statement specifies the identifier value of the site-level aggregator - (SLA) on the interface. ID must be a decimal number greater then 0 which - fits in the length of SLA IDs (see below). For example, if ID is 1 and the - client is delegated an IPv6 prefix 2001:db8:ffff::/48, dhcp6c will combine - the two values into a single IPv6 prefix, 2001:db8:ffff:1::/64, and will - configure the prefix on the specified interface. +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 +********* Operation -========= +********* .. opcmd:: show interfaces pppoe <interface> @@ -237,7 +220,7 @@ Operation backlog 0b 0p requeues 0 Connect/Disconnect ------------------- +================== .. opcmd:: disconnect interface <interface> @@ -249,8 +232,9 @@ Connect/Disconnect Test connecting given connection-oriented interface. `<interface>` can be ``pppoe0`` as example. +******* Example -======= +******* Requirements: @@ -266,7 +250,8 @@ Requirements: * With the ``default-route`` option set to ``auto``, VyOS will only add the default gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a dual WAN connection, - change the ``default-route`` option to ``force``. + change the ``default-route`` option to ``force``. You could also install + a static route and set the ``default-route`` option to ``none``. * With the ``name-server`` option set to ``none``, VyOS will ignore the nameservers your ISP sens you and thus you can fully rely on the ones you have configured statically. @@ -293,7 +278,7 @@ assigning it to the pppoe0 itself as shown here: set interfaces pppoe pppoe0 firewall out name NET-OUT VLAN Example ------------- +============ Some recent ISPs require you to build the PPPoE connection through a VLAN interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS @@ -313,10 +298,14 @@ which is the default VLAN for Deutsche Telekom: IPv6 DHCPv6-PD Example ---------------------- +.. stop_vyoslinter + The following configuration will assign a /64 prefix out of a /56 delegation to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. If you do not know the prefix size delegated to you, start with sla-len 0. +.. start_vyoslinter + .. code-block:: none set interfaces pppoe pppoe0 authentication user vyos @@ -325,5 +314,4 @@ If you do not know the prefix size delegated to you, start with sla-len 0. set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-id 0 set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-len 8 set interfaces pppoe pppoe0 ipv6 address autoconf - set interfaces pppoe pppoe0 ipv6 enable set interfaces pppoe pppoe0 source-interface eth1 diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst index a2066555..0471d2e1 100644 --- a/docs/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -38,52 +38,28 @@ Ethernet interfaces: - Network switches with security settings allowing only a single MAC address - xDSL modems that try to lear the MAC address of the NIC +************* Configuration -============= +************* -Address -------- +Common interface configuration +============================== -.. cfgcmd:: set interfaces pseudo-ethernet <interface> address <address | dhcp | dhcpv6> +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 - .. include:: common-ip-ipv6-addr.txt - - Example: - - .. code-block:: none - - set interfaces pseudo-ethernet peth0 address 192.0.2.1/24 - set interfaces pseudo-ethernet peth0 address 192.0.2.2/24 - set interfaces pseudo-ethernet peth0 address 2001:db8::ffff/64 - set interfaces pseudo-ethernet peth0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -Physical Asignment ------------------- +Pseudo Ethernet/MACVLAN options +=============================== .. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo Ethernet `<interface>`. -Link Administration -------------------- - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. +VLAN +==== +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: pseudo-ethernet + :var1: peth0 diff --git a/docs/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index f20127f5..d2d63ce2 100644 --- a/docs/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -13,6 +13,13 @@ GRE options that can be useful. All those protocols are grouped under ``interfaces tunnel`` in VyOS. Let's take a closer look at the protocols and options currently supported by VyOS. +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: tunnel + :var1: tun0 + IPIP ---- @@ -86,25 +93,31 @@ An example: set interfaces tunnel tun0 remote-ip 192.0.2.20 set interfaces tunnel tun0 address 2001:db8:bb::1/64 -A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`. +A full example of a Tunnelbroker.net config can be found at +:ref:`here <examples-tunnelbroker-ipv6>`. Generic Routing Encapsulation (GRE) ----------------------------------- A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP -protocol 47.The main benefit of a GRE tunnel is that you are able to route -traffic across disparate networks. GRE also supports multicast traffic and -supports routing protocols that leverage multicast to form neighbor adjacencies. +protocol 47.The main benefit of a GRE tunnel is that you are able to carry +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + Configuration ^^^^^^^^^^^^^ A basic configuration requires a tunnel source (local-ip), a tunnel destination (remote-ip), an encapsulation type (gre), and an address (ipv4/ipv6).Below is a -configuration example taken from a VyOS router and a Cisco IOS router. The main -difference between these two configurations is that VyOS requires you -explicitly configure the encapsulation type. The Cisco router defaults to gre -ip otherwise it would have to be configured as well. +basic IPv4 only configuration example taken from a VyOS router and a Cisco IOS +router. The main difference between these two configurations is that VyOS +requires you explicitly configure the encapsulation type. The Cisco router +defaults to gre ip otherwise it would have to be configured as well. **VyOS Router:** @@ -124,6 +137,71 @@ ip otherwise it would have to be configured as well. tunnel source 203.0.113.10 tunnel destination 198.51.100.2 +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' + set interfaces tunnel tun101 address '192.168.5.1/30' + set interfaces tunnel tun101 encapsulation 'ip6gre' + set interfaces tunnel tun101 local-ip '2001:db8:babe:face::3afe:3' + set interfaces tunnel tun101 remote-ip '2001:db8:9bb:3ce::5' + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +.. code-block:: none + + # cat /etc/systemd/network/gre-example.netdev + [NetDev] + Name=gre-example + Kind=ip6gre + MTUBytes=14180 + + [Tunnel] + Remote=2001:db8:babe:face::3afe:3 + + + # cat /etc/systemd/network/gre-example.network + [Match] + Name=gre-example + + [Network] + Address=2001:db8:feed:beef::2/126 + + [Address] + Address=192.168.5.2/30 + +Tunnel keys +^^^^^^^^^^^ + +GRE is also the only classic protocol that allows creating multiple tunnels +with the same source and destination due to its support for tunnel keys. +Despite its name, this feature has nothing to do with security: it's simply +an identifier that allows routers to tell one tunnel from another. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + Troubleshooting ^^^^^^^^^^^^^^^ @@ -180,26 +258,8 @@ that are discarding IP protocol 47 or blocking your source/desintation traffic. 4 packets transmitted, 4 received, 0% packet loss, time 3008ms rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms -Virtual Tunnel Interface (VTI) ------------------------------- - -Set Virtual Tunnel Interface - -.. code-block:: none - - set interfaces vti vti0 address 192.168.2.249/30 - set interfaces vti vti0 address 2001:db8:2::249/64 - -Results in: - -.. code-block:: none - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } +.. note:: There is also a GRE over IPv6 encapsulation available, it is + called: ``ip6gre``. .. _`other proposals`: https://www.isc.org/othersoftware/ .. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst new file mode 100644 index 00000000..62cd13f3 --- /dev/null +++ b/docs/configuration/interfaces/vti.rst @@ -0,0 +1,22 @@ +############################## +Virtual Tunnel Interface (VTI) +############################## + + +Set Virtual Tunnel Interface + +.. code-block:: none + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: none + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + }
\ No newline at end of file diff --git a/docs/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index a11f4b62..ca25d21e 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -36,106 +36,58 @@ may be blocked by the hypervisor. Configuration ============= -Address -------- - -.. cfgcmd:: set interfaces vxlan <interface> address <address> - - Configure VXLAN interface `<interface>` with one or more interface - addresses. Address can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - - Example: - - .. code-block:: none - - set interfaces vxlan vxlan0 address 192.0.2.1/24 - set interfaces vxlan vxlan0 address 192.0.2.2/24 - set interfaces vxlan vxlan0 address 2001:db8::ffff/64 - set interfaces vxlan vxlan0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces vxlan <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces vxlan <interface> ipv6 address eui64 <prefix> - - :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in - :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. - - .. code-block:: none - - set interfaces vxlan vxlan0 ipv6 address eui64 2001:db8:beef::/64 +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 +VXLAN specific options +----------------------- .. cfgcmd:: set interfaces vxlan <interface> vni <number> - Each VXLAN segment is identified through a 24-bit segment ID, termed the - :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows - up to 16M VXLAN segments to coexist within the same administrative domain. - -Multicast -^^^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. - Interface used for VXLAN underlay. This is mandatory when using VXLAN via - a multicast network. VXLAN traffic will always enter and exit this interface. +.. cfgcmd:: set interfaces vxlan <interface> port <port> + Configure port number of remote VXLAN endpoint. -.. cfgcmd:: set interfaces vxlan <interface> group <address> + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. - Multicast group address for VXLAN interface. VXLAN tunnels can be built - either via Multicast or via Unicast. +.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> - Both IPv4 and IPv6 multicast is possible. + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. Unicast ^^^^^^^ .. cfgcmd:: set interfaces vxlan <interface> remote <address> - IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the - remote IPv4/IPv6 address can set directly. - - -.. cfgcmd:: set interfaces vxlan <interface> port <port> - - Configure port number of remote VXLAN endpoint. - - .. note:: As VyOS is Linux based the default port used is not using 4789 - as the default IANA-assigned destination UDP port number. Instead VyOS - uses the Linux default port of 8472. - -L2VVPN / EVPN -^^^^^^^^^^^^^ + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. -.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> - - Source IP address used for VXLAN underlay. This is mandatory when using - VXLAN via L2VPN/EVPN. - - -Link Administration -------------------- +Multicast +^^^^^^^^^ -.. cfgcmd:: set interfaces vxlan <interface> description <description> +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. -.. cfgcmd:: set interfaces vxlan <interface> disable - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. +.. cfgcmd:: set interfaces vxlan <interface> group <address> -.. cfgcmd:: set interfaces vxlan <interface> mtu <mtu> + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. - Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It - is the size (in bytes) of the largest ethernet frame sent on this link. - MTU ranges from 1450 to 9000 bytes. For best performance you should have - a MTU > 1550 bytes on your underlay. + Both IPv4 and IPv6 multicast is possible. Multicast VXLAN =============== @@ -230,7 +182,7 @@ traffic from. set interfaces bridge br241 member interface 'vxlan241' set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' set interfaces vxlan vxlan241 vni '241' ! Our seconds vxlan interface @@ -239,7 +191,7 @@ traffic from. set interfaces bridge br242 member interface 'vxlan242' set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' **Leaf3 configuration:** @@ -255,7 +207,7 @@ traffic from. set interfaces bridge br241 member interface 'vxlan241' set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' set interfaces vxlan vxlan241 vni '241' ! Our seconds vxlan interface @@ -264,7 +216,7 @@ traffic from. set interfaces bridge br242 member interface 'vxlan242' set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' As you can see, Leaf2 and Leaf3 configuration is almost identical. There are @@ -288,8 +240,8 @@ advertised. set interfaces bridge br241 member interface 'eth1.241' set interfaces bridge br241 member interface 'vxlan241' -Binds eth1.241 and vxlan241 to each other by making them both member interfaces of -the same bridge. +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. .. code-block:: none @@ -300,7 +252,7 @@ same on all Leafs that has this interface. .. code-block:: none - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' Sets the interface to listen for multicast packets on. Could be a loopback, not yet tested. @@ -314,7 +266,7 @@ multicast-address. .. code-block:: none - set interfaces vxlan vxlan241 remote-port 12345 + set interfaces vxlan vxlan241 port 12345 The destination port used for creating a VXLAN interface in Linux defaults to its pre-standard value of 8472 to preserve backwards compatibility. A @@ -331,7 +283,7 @@ set directly. Let's change the Multicast example from above: # leaf2 and leaf3 delete interfaces vxlan vxlan241 group '239.0.0.241' - delete interfaces vxlan vxlan241 link 'eth0' + delete interfaces vxlan vxlan241 source-interface 'eth0' # leaf2 set interface vxlan vxlan241 remote 10.1.3.3 @@ -340,4 +292,4 @@ set directly. Let's change the Multicast example from above: set interface vxlan vxlan241 remote 10.1.2.2 The default port udp is set to 8472. -It can be changed with ``set interface vxlan <vxlanN> remote-port <port>`` +It can be changed with ``set interface vxlan <vxlanN> port <port>`` diff --git a/docs/vpn/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index 3580fac3..852ff520 100644 --- a/docs/vpn/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -78,7 +78,7 @@ one. set interfaces wireguard wg01 peer to-wg02 port '12345' set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 + set protocols static route 10.2.0.0/24 interface wg01 The last step is to define an interface route for 10.2.0.0/24 to get through the WireGuard interface `wg01`. Multiple IPs or networks can be @@ -113,7 +113,7 @@ the public key, which needs to be shared with the peer. set interfaces wireguard wg01 peer to-wg02 port '12345' set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01 + set protocols static route 10.1.0.0/24 interface wg01 Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard @@ -262,4 +262,8 @@ Operational commands vyos@wg01# wireguard keypair default +.. stop_vyoslinter + .. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index 8b1195fa..097d7c49 100644 --- a/docs/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,7 +1,8 @@ .. _wireless-interface: +################### Wireless LAN (WiFi) -------------------- +################### :abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless support (commonly referred to as Wi-Fi) by means of compatible hardware. If your @@ -22,39 +23,287 @@ If the system detects an unconfigured wireless device, it will be automatically added the configuration tree, specifying any detected settings (for example, its MAC address) and configured to run in monitor mode. -To be able to use the wireless interfaces you will first need to set a -regulatory domain with the country code of your location. +************* +Configuration +************* -.. cfgcmd:: set system wifi-regulatory-domain DE +Common interface configuration +============================== - Configure system wide Wi-Fi regulatory domain. A reboot is required for this - change to be enabled. +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 -Configuring Access-Point -^^^^^^^^^^^^^^^^^^^^^^^^ +Wireless options +================ -The following example creates a WAP. When configuring multiple WAP interfaces, -you must specify unique IP addresses, channels, Network IDs commonly referred -to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. +.. cfgcmd:: set interfaces wireless <interface> channel <number> -The WAP in this example has the following characteristics: + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. + +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. + +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. + +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. + +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec + +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. + +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. + +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames + +.. cfgcmd:: set interfaces wireless <interface> type + <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel + +PPDU +---- + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt + +HT (High Throughput) capabilities (802.11n) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for + use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu + <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +VHT (Very High Throughput) capabilities (802.11ac) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + center-channel-freq <freq-1 | freq-2> <number> + + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) + + <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + short-gi <80 | 160> + + Short GI capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field + +Wireless options (Station/Client) +================================= + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (``phy0``) is used. .. code-block:: none - set interfaces wireless wlan0 address '192.168.2.1/24' - set interfaces wireless wlan0 type access-point - set interfaces wireless wlan0 channel 1 - set interfaces wireless wlan0 mode n - set interfaces wireless wlan0 ssid 'TEST' - set interfaces wireless wlan0 security wpa mode wpa2 - set interfaces wireless wlan0 security wpa cipher CCMP - set interfaces wireless wlan0 security wpa passphrase '12345678' + set interfaces wireless wlan0 type station + set interfaces wireless wlan0 address dhcp + set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 security wpa Resulting in @@ -63,32 +312,18 @@ Resulting in interfaces { [...] wireless wlan0 { - address 192.168.2.1/24 - channel 1 - mode n - security { - wpa { - cipher CCMP - mode wpa2 - passphrase "12345678" - } - } - ssid "TEST" - type access-point + address dhcp + security { + wpa { + passphrase "12345678" + } } - } - system { - [...] - wifi-regulatory-domain DE - } - -To get it to work as a access point with this configuration you will need -to set up a DHCP server to work with that network. You can - of course - also -bridge the Wireless interface with any configured bridge -(:ref:`bridge-interface`) on the system. + ssid TEST + type station + } -WPA/WPA2 enterprise -******************* +Security +======== :abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with 802.1x based authentication can be used to authenticate users or computers @@ -154,39 +389,26 @@ Resulting in } -Configuring Wireless Station -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +VLAN +==== -The example creates a wireless station (commonly referred to as Wi-Fi client) -that accesses the network through the WAP defined in the above example. The -default physical device (``phy0``) is used. +Regular VLANs (802.1q) +---------------------- -.. code-block:: none +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 - set interfaces wireless wlan0 type station - set interfaces wireless wlan0 address dhcp - set interfaces wireless wlan0 ssid Test - set interfaces wireless wlan0 security wpa +QinQ (802.1ad) +-------------- -Resulting in +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 -.. code-block:: none - - interfaces { - [...] - wireless wlan0 { - address dhcp - security { - wpa { - passphrase "12345678" - } - } - ssid TEST - type station - } - -Operational Commands -^^^^^^^^^^^^^^^^^^^^ +********* +Operation +********* .. opcmd:: show interfaces wireless info @@ -233,8 +455,8 @@ information about all wireless interfaces. .. opcmd:: show interfaces wireless <wlanX> -This command shows both status and statistics on the specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. .. code-block:: none @@ -308,3 +530,61 @@ in station mode. 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 + +******** +Examples +******** + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '12345678' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +(:ref:`bridge-interface`) on the system. diff --git a/docs/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst index 5cded6c5..a65a47f4 100644 --- a/docs/interfaces/wirelessmodem.rst +++ b/docs/configuration/interfaces/wirelessmodem.rst @@ -4,15 +4,31 @@ WirelessModem (WWAN) #################### +The wirelessmodem interface provides access (through a wireless modem/wwan) +to wireless networks provided by various cellular providers. VyOS uses the +interfaces wirelessmodem subsystem for configuration. + +************* Configuration -############# +************* -The wirelessmodem interface provides access (through a wireless modem/wwan) to -wireless networks provided by various cellular providers. VyOS uses the -interfaces wirelessmodem subsystem for configuration. +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: wirelessmodem + :var1: wlm0 -Address -------- +WirelessModem (WWAN) options +============================ .. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> @@ -35,50 +51,18 @@ Address Do not install DNS nameservers received from ISP into system wide nameserver list. -.. cfgcmd:: set interfaces wirelessmodem <interface> ondemand +.. cfgcmd:: set interfaces wirelessmodem <interface> connect-on-demand - Enables or disables on-demand WWAN connection. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPP connection automatically once traffic passes through the interface. A disabled on-demand connection is established at boot time and remains up. If the link fails for any reason, the link is brought back up immediately. -Link Administration -------------------- - -.. cfgcmd:: set interfaces wirelessmodem <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces wirelessmodem <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - state. - -.. cfgcmd:: set interfaces wirelessmodem <interface> mtu <mtu> - - Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It - is the size (in bytes) of the largest ethernet frame sent on this link. - -Example -======= - -The following example is based on a Sierra Wireless MC7710 miniPCIe card (only -the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card -is assembled into a :ref:`pc-engines-apu4`. - -.. code-block:: none - - set interfaces wirelessmodem wlm0 apn 'internet.telekom' - set interfaces wirelessmodem wlm0 backup distance '100' - set interfaces wirelessmodem wlm0 device 'ttyUSB2' - set interfaces wirelessmodem wlm0 disable - set interfaces wirelessmodem wlm0 no-peer-dns - +********* Operation -========= +********* .. opcmd:: show interfaces wirelessmodem <interface> @@ -112,8 +96,26 @@ Operation Displays log information for a WWAN interface. + +******* +Example +******* + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a :ref:`pc-engines-apu4`. + +.. code-block:: none + + set interfaces wirelessmodem wlm0 apn 'internet.telekom' + set interfaces wirelessmodem wlm0 backup distance '100' + set interfaces wirelessmodem wlm0 device 'ttyUSB2' + set interfaces wirelessmodem wlm0 disable + set interfaces wirelessmodem wlm0 no-peer-dns + +***************** Supported Modules -################# +***************** The following hardware modules have been tested successfully in an :ref:`pc-engines-apu4` board: @@ -123,4 +125,4 @@ The following hardware modules have been tested successfully in an * Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) * Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) * Huawei ME909u-521 miniPCIe card (LTE) - +* Huawei ME909s-120 miniPCIe card (LTE) diff --git a/docs/load-balancing.rst b/docs/configuration/loadbalancing/index.rst index 07c18217..7d675c1b 100644 --- a/docs/load-balancing.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -4,8 +4,11 @@ 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. +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: @@ -26,9 +29,11 @@ Let's assume we have two DHCP WAN interfaces and one LAN (eth2): 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. +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: @@ -50,8 +55,10 @@ Create a load balancing rule, rule can be a number between 1 and 9999: 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. +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 @@ -63,15 +70,18 @@ Per default outbound traffic is distributed randomly across available interfaces 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: +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 <rule> limit <parameter> -* ``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``. +* ``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. @@ -79,11 +89,15 @@ 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. +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: +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 @@ -92,7 +106,8 @@ Packet-based balancing can lead to a better balance across interfaces when out o Exclude traffic *************** -To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: +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 @@ -102,8 +117,11 @@ To exclude traffic from load balancing, traffic matching an exclude rule is not 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: +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 @@ -114,22 +132,26 @@ If an interface fails the health check it is removed from the load balancer's po success-count Success count +> test Rule number -Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` +Specify nexthop on the path to destination, ``ipv4-address`` can be set to +``dhcp`` .. code-block:: none set load-balancing wan interface-health <interface> nexthop <ipv4-address> -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. +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 <interface> failure-count <number> set load-balancing wan interface-health <interface> success-count <number> -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: +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 @@ -141,17 +163,28 @@ For multi target health checking multiple tests can be defined: 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 +* ``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: +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 @@ -159,8 +192,16 @@ This works through automatically generated source NAT (SNAT) rules, these rules Sticky Connections ------------------ +Inbound connections to a WAN interface can be improperly handled when the reply +is sent back to the client. -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. +.. 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 @@ -170,17 +211,23 @@ This can be achieved by enabling sticky connections in the load balancing: 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: +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 <number> failover -Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: +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 @@ -188,12 +235,14 @@ Because existing sessions do not automatically fail over to a new path, the sess .. warning:: - Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. + 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: +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 @@ -206,7 +255,8 @@ Two environment variables are available: .. warning:: - Blocking call with no timeout. System will become unresponsive if script does not return! + Blocking call with no timeout. System will become unresponsive if script + does not return! Handling and monitoring ----------------------- diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst new file mode 100644 index 00000000..90275226 --- /dev/null +++ b/docs/configuration/nat/index.rst @@ -0,0 +1,12 @@ +.. _nat: + +### +NAT +### + +.. toctree:: + :maxdepth: 1 + :includehidden: + + nat44 + nat66 diff --git a/docs/nat.rst b/docs/configuration/nat/nat44.rst index 17698c26..59cee741 100644 --- a/docs/nat.rst +++ b/docs/configuration/nat/nat44.rst @@ -1,8 +1,8 @@ -.. _nat: +.. _nat44: -### -NAT -### +##### +NAT44 +##### :abbr:`NAT (Network Address Translation)` is a common method of remapping one IP address space into another by modifying network address @@ -167,8 +167,8 @@ rule. 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. + applies to. Only packets matching the specified protocol are NATed. + By default this applies to `all` protocols. Example: @@ -188,13 +188,13 @@ rule. * 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 + * Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.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 address 203.0.113.0/24 set nat source rule 30 source port 80,443 @@ -600,7 +600,7 @@ 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 +.. figure:: /_static/images/nat_before_vpn_topology.png :scale: 100 % :alt: NAT before VPN Topology diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst new file mode 100644 index 00000000..bcf5570f --- /dev/null +++ b/docs/configuration/nat/nat66.rst @@ -0,0 +1,127 @@ +.. _nat66: + +############ +NAT66(NPTv6) +############ + +:abbr:`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address translation technology based +on IPv6 networks, used to convert an IPv6 address prefix in an IPv6 message into another IPv6 +address prefix. We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source and destination address +translation functions. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat66: + +SNAT66 +^^^^^^ + +:abbr:`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion function is mainly used in +the following scenarios: + +* A single internal network and external network. Use the NAT66 device to connect a single internal + network and public network, and the hosts in the internal network use IPv6 address prefixes that + only support routing within the local range. When a host in the internal network accesses the + external network, the source IPv6 address prefix in the message will be converted into a + global unicast IPv6 address prefix by the NAT66 device. +* Redundancy and load sharing. There are multiple NAT66 devices at the edge of an IPv6 network + to another IPv6 network. The path through the NAT66 device to another IPv6 network forms an + equivalent route, and traffic can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these NAT66 devices, so that any + NAT66 device can handle IPv6 traffic between different sites. +* Multi-homed. In a multi-homed network environment, the NAT66 device connects to an + internal network and simultaneously connects to different external networks. Address + translation can be configured on each external network side interface of the NAT66 + device to convert the same internal network address into different external network + addresses, and realize the mapping of the same internal address to multiple external addresses. + +.. _destination-nat66: + +DNAT66 +^^^^^^ + +The :abbr:`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` destination address translation +function is used in scenarios where the server in the internal network provides services to the external +network, such as providing Web services or FTP services to the external network. By configuring the mapping +relationship between the internal server address and the external network address on the external network +side interface of the NAT66 device, external network users can access the internal network server through +the designated external network address. + +Prefix Conversion +------------------ + +Source Prefix +^^^^^^^^^^^^^ + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The :ref:`source-nat66` rule replaces the source address of the packet and calculates the +converted address using the prefix specified in the rule. + +Example: + +* Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +* Output from `eth0` network interface + +.. code-block:: none + + set nat66 source rule 1 outbound-interface 'eth0' + set nat66 source rule 1 source prefix 'fc01::/64' + set nat66 source rule 1 translation prefix 'fc00::/64' + +Destination Prefix +^^^^^^^^^^^^^^^^^^ + +For the :ref:`destination-nat66` rule, the destination address of the packet is +replaced by the address calculated from the specified address or prefix in the +`translation address` command + +Example: + +* Convert the address prefix of a single `fc00::/64` network to `fc01::/64` +* Input from `eth0` network interface + +.. code-block:: none + + set nat66 destination rule 1 inbound-interface 'eth0' + set nat66 destination rule 1 destination address 'fc00::/64' + set nat66 destination rule 1 translation address 'fc01::/64' + +Configuration Examples +====================== + +Use the following topology to build a nat66 based isolated network between internal +and external networks (dynamic prefix is not supported): + +.. figure:: /_static/images/vyos_1_4_nat66_simple.png + :alt: VyOS NAT66 Simple Configure + +R1: + +.. code-block:: none + + set interfaces ethernet eth0 ipv6 address autoconf + set interfaces ethernet eth1 address 'fc01::1/64' + set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' + set nat66 destination rule 1 inbound-interface 'eth0' + set nat66 destination rule 1 translation address 'fc01::/64' + set nat66 source rule 1 outbound-interface 'eth0' + set nat66 source rule 1 source prefix 'fc01::/64' + set nat66 source rule 1 translation prefix 'fc00:470:f1cd:101::/64' + +R2: + +.. code-block:: none + + set interfaces bridge br1 address 'fc01::2/64' + set interfaces bridge br1 member interface eth0 + set interfaces bridge br1 member interface eth1 + set protocols static route6 ::/0 next-hop fc01::1 + set service router-advert interface br1 prefix ::/0 diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst new file mode 100644 index 00000000..c772306f --- /dev/null +++ b/docs/configuration/policy/index.rst @@ -0,0 +1,207 @@ +.. 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. + + +.. _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.2.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. + +* ``203.0.113.0.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 '203.0.113.0.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 '203.0.113.0.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 '203.0.113.0.254' + set policy local-route rule 101 source '203.0.113.0.253' + set policy local-route rule 101 source '198.51.100.0/24' + diff --git a/docs/routing/bfd.rst b/docs/configuration/protocols/bfd.rst index 1d494332..8d19334c 100644 --- a/docs/routing/bfd.rst +++ b/docs/configuration/protocols/bfd.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _routing-bfd: @@ -9,6 +9,12 @@ BFD :abbr:`BFD (Bidirectional Forwarding Detection)` is described and extended by the following RFCs: :rfc:`5880`, :rfc:`5881` and :rfc:`5883`. +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. Configure BFD ============= @@ -25,19 +31,22 @@ Configure BFD Allow this BFD peer to not be directly connected -.. cfgcmd:: set protocols bfd peer <address> source [address <address> | interface <interface>] +.. cfgcmd:: set protocols bfd peer <address> source + [address <address> | interface <interface>] Bind listener to specifid interface/address, mandatory for IPv6 .. cfgcmd:: set protocols bfd peer <address> interval echo-interval <10-60000> - The minimal echo receive transmission interval that this system is capable of handling + The minimal echo receive transmission interval that this system is + capable of handling .. cfgcmd:: set protocols bfd peer <address> interval multiplier <2-255> Remote transmission interval will be multiplied by this value -.. cfgcmd:: set protocols bfd peer <address> interval [receive | transmit] <10-60000> +.. cfgcmd:: set protocols bfd peer <address> interval + [receive | transmit] <10-60000> Interval in milliseconds @@ -58,17 +67,24 @@ Enable BFD in BGP Enable BFD on a BGP peer group - Enable BFD in OSPF ------------------ -.. cfgcmd:: set interfaces ethernet <ethN> ip ospf bfd +.. cfgcmd:: set interfaces ethernet <interface> ip ospf bfd + + Enable BFD for OSPF on a interface - Enable BFD for ospf on a interface +.. cfgcmd:: set interfaces ethernet <interface> ipv6 ospfv3 bfd + + Enable BFD for OSPFv3 on a interface + + +Enable BFD in ISIS +------------------ -.. cfgcmd:: set interfaces ethernet <ethN> ipv6 ospfv3 bfd +.. cfgcmd:: set protocols isis <name> interface <interface> bfd - Enable BFD for ospfv3 on a interface + Enable BFD for ISIS on a interface diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst new file mode 100644 index 00000000..6b6605a6 --- /dev/null +++ b/docs/configuration/protocols/bgp.rst @@ -0,0 +1,1179 @@ +.. _bgp: + +### +BGP +### + +:abbr:`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` +adds multiprotocol support to BGP. + +VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +Basic Concepts +============== + +.. _bgp-autonomous-systems: + +Autonomous Systems +------------------ + +From :rfc:`1930`: + + An AS is a connected group of one or more IP prefixes run by one or more + network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each AS has an identifying number associated with it called an :abbr:`ASN +(Autonomous System Number)`. This is a two octet value ranging in value from 1 +to 65535. The AS numbers 64512 through 65535 are defined as private AS numbers. +Private AS numbers must not be advertised on the global Internet. The 2-byte AS +number range has been exhausted. 4-byte AS numbers are specified in +:rfc:`6793`, and provide a pool of 4294967296 AS numbers. + +The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +.. _bgp-address-families: + +Address Families +---------------- + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +.. _bgp-route-selection: + +Route Selection +--------------- + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + :cfgcmd:`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + :cfgcmd:`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest `router-ID`. If the route has an + `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is + used, otherwise the `router-ID` of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +.. _bgp-capability-negotiation: + +Capability Negotiation +---------------------- + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. :abbr:`IETF (Internet Engineering Task Force)` +:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in :rfc:`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. :rfc:`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +.. _bgp-router-configuration: + +BGP Router Configuration +======================== + +First of all you must configure BGP router with the :abbr:`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +The BGP protocol uses the AS number for detecting whether the BGP connection +is internal or external. VyOS does not have a special command to start the BGP +process. The BGP process starts when the first neighbor is configured. + +Peers Configuration +------------------- + +Defining Peers +^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + <nasn> + + This command creates a new neighbor whose remote-as is <nasn>. The neighbor + address can be an IPv4 address or an IPv6 address or an interface to use + for the connection. The command it applicable for peer and peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + internal + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is different than mine as specified under the :cfgcmd:`protocols + bgp <asn>` command the connection will be denied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + external + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is the same as mine as specified under the :cfgcmd:`protocols + bgp <asn>` command the connection will be denied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> shutdown + + This command disable the peer or peer group. To reenable the peer use + the delete form of this command. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> description + <text> + + Set description of the peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> update-source + <address|interface> + + Specify the IPv4 source address to use for the BGP session to this neighbor, + may be specified as either an IPv4 address directly or as an interface name. + + +Capability Negotiation +^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> capability + dynamic + + This command would allow the dynamic update of capabilities over an + established BGP session. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> capability + extended-nexthop + + Allow bgp to negotiate the extended-nexthop capability with it’s peer. + If you are peering over a IPv6 Link-Local address then this capability + is turned on automatically. If you are peering over a IPv6 Global Address + then turning on this command will allow BGP to install IPv4 routes with + IPv6 nexthops if you do not have IPv4 configured on interfaces. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-capability-negotiation + + Suppress sending Capability Negotiation as OPEN message optional + parameter to the peer. This command only affects the peer is + configured other than IPv4 unicast configuration. + + When remote peer does not have capability negotiation feature, + remote peer will not send any capabilities at all. In that case, + bgp configures the peer with configured capabilities. + + You may prefer locally configured capabilities more than the negotiated + capabilities even though remote peer sends capabilities. If the peer is + configured by :cfgcmd:`override-capability`, VyOS ignores received + capabilities then override negotiated capabilities with configured values. + + Additionally you should keep in mind that this feature fundamentally + disables the ability to use widely deployed BGP features. BGP unnumbered, + hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, + and graceful restart. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + override-capability + + This command allow override the result of Capability Negotiation with + local configuration. Ignore remote peer’s capability value. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + strict-capability-match + + This command forces strictly compare remote capabilities and local + capabilities. If capabilities are different, send Unsupported Capability + error then reset connection. + + You may want to disable sending Capability Negotiation OPEN message + optional parameter to the peer when remote peer does not implement + Capability Negotiation. Please use :cfgcmd:`disable-capability-negotiation` + command to disable the feature. + + +Peer Parameters +^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> allowas-in number <number> + + This command accept incoming routes with AS path containing AS + number with the same value as the current system AS. This is + used when you want to use the same AS number in your sites, + but you can’t connect them directly. + + The number parameter (1-10) configures the amount of accepted + occurences of the system AS number in AS path. + + This command is only allowed for eBGP peers. It is not applicable + for peer groups. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> as-override + + This command override AS number of the originating router with + the local AS number. + + Usually this configuration is used in PEs (Provider Edge) to + replace the incoming customer AS number so the connected CE ( + Customer Edge) can use the same AS number as the other customer + sites. This allows customers of the provider network to use the + same AS number across their sites. + + This command is only allowed for eBGP peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> attribute-unchanged <as-path|med|next-hop> + + This command specifies attributes to be left unchanged for + advertisements sent to a peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> maximum-prefix <number> + + This command specifies a maximum number of prefixes we can receive + from a given peer. If this number is exceeded, the BGP session + will be destroyed. The number range is 1 to 4294967295. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> nexthop-self + + This command forces the BGP speaker to report itself as the + next hop for an advertised route it advertised to a neighbor. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> remove-private-as + + This command removes the private ASN of routes that are advertised + to the configured peer. It removes only private ASNs on routes + advertised to EBGP peers. + + If the AS-Path for the route has only private ASNs, the private + ASNs are removed. + + If the AS-Path for the route has a private ASN between public + ASNs, it is assumed that this is a design choice, and the + private ASN is not removed. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> soft-reconfiguration inbound + + Changes in BGP policies require the BGP session to be cleared. Clearing has a + large negative impact on network operations. Soft reconfiguration enables you + to generate inbound updates from a neighbor, change and activate BGP policies + without clearing the BGP session. + + This command specifies that route updates received from this neighbor will be + stored unmodified, regardless of the inbound policy. When inbound soft + reconfiguration is enabled, the stored updates are processed by the new + policy configuration to create new inbound updates. + + .. note:: Storage of route updates uses memory. If you enable soft + reconfiguration inbound for multiple neighbors, the amount of memory used + can become significant. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> weight <number> + + This command specifies a default weight value for the neighbor’s + routes. The number range is 1 to 65535. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + advertisement-interval <seconds> + + This command specifies the minimum route advertisement interval for + the peer. The interval value is 0 to 600 seconds, with the default + advertisement interval being 0. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-connected-check + + This command allows peerings between directly connected eBGP peers + using loopback addresses without adjusting the default TTL of 1. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-send-community <extended|standard> + + This command specifies that the community attribute should not be sent + in route updates to a peer. By default community attribute is sent. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> ebgp-multihop + <number> + + This command allows sessions to be established with eBGP neighbors + when they are multiple hops away. When the neighbor is not directly + connected and this knob is not enabled, the session will not establish. + The number of hops range is 1 to 255. This command is mutually + exclusive with :cfgcmd:`ttl-security hops`. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> local-as <asn> + [no-prepend] [replace-as] + + Specify an alternate AS for this BGP process when interacting with + the specified peer or peer group. With no modifiers, the specified + local-as is prepended to the received AS_PATH when receiving routing + updates from the peer, and prepended to the outgoing AS_PATH (after + the process local AS) when transmitting local routes to the peer. + + If the :cfgcmd:`no-prepend` attribute is specified, then the supplied + local-as is not prepended to the received AS_PATH. + + If the :cfgcmd:`replace-as` attribute is specified, then only the supplied + local-as is prepended to the AS_PATH when transmitting local-route + updates to this peer. + + .. note:: This command is only allowed for eBGP peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> passive + + Configures the BGP speaker so that it only accepts inbound connections + from, but does not initiate outbound connections to the peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> password + <text> + + This command specifies a MD5 password to be used with the tcp socket that + is being used to connect to the remote peer. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> ttl-security + hops <number> + + This command enforces Generalized TTL Security Mechanism (GTSM), + as specified in :rfc:`5082`. With this command, only neighbors + that are the specified number of hops away will be allowed to + become neighbors. The number of hops range is 1 to 254. This + command is mutually exclusive with :cfgcmd:`ebgp-multihop`. + + +Peer Groups +^^^^^^^^^^^ + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +.. cfgcmd:: set protocols bgp <asn> peer-group <name> + + This command defines a new peer group. You can specify to the group the same + parameters that you can specify for specific neighbors. + + .. note:: If you apply a parameter to an individual neighbor IP address, you + override the action defined for a peer group that includes that IP + address. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> peer-group + <name> + + This command bind specific peer to peer group with a given name. + + +Network Advertisement Configuration +----------------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + network <prefix> + + This command is used for advertising IPv4 or IPv6 networks. + + .. note:: By default, the BGP prefix is advertised even if it's not present + in the routing table. This behaviour differs from the implementation of + some vendors. + +.. cfgcmd:: set protocols bgp <asn> parameters network-import-check + + This configuration modifies the behavior of the network statement. If you + have this configured the underlying network must exist in the routing table. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> default-originate [route-map <name>] + + By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is + in routing table. When you want to announce default routes to the peer, use + this command. Using optional argument :cfgcmd:`route-map` you can inject the + default route to given neighbor only if the conditions in the route map are + met. + + +Route Aggregation Configuration +------------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> + + This command specifies an aggregate address. The router will also + announce longer-prefixes inside of the aggregate address. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> as-set + + This command specifies an aggregate address with a mathematical set of + autonomous systems. This command summarizes the AS_PATH attributes of + all the individual routes. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> summary-only + + This command specifies an aggregate address and provides that + longer-prefixes inside of the aggregate address are suppressed + before sending BGP updates out to peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> unsuppress-map <name> + + This command applies route-map to selectively unsuppress prefixes + suppressed by summarisation. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> + + This command redistributes routing information from the given route source + to the BGP process. There are six modes available for route source: + connected, kernel, ospf, rip, static, table. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> metric <number> + + This command specifies metric (MED) for redistributed routes. The + metric range is 0 to 4294967295. There are six modes available for + route source: connected, kernel, ospf, rip, static, table. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes. + There are six modes available for route source: connected, kernel, + ospf, rip, static, table. + + +General Configuration +--------------------- + +Common parametrs +^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> parameters router-id <id> + + This command specifies the router-ID. If router ID is not specified it will + use the highest interface IP address. + +.. cfgcmd:: set protocols bgp <asn> maximum-paths <ebgp|ibgp> <number> + + This command defines the maximum number of parallel routes that + the BGP can support. In order for BGP to use the second path, the + following attributes have to match: Weight, Local Preference, AS + Path (both AS number and AS path length), Origin code, MED, IGP + metric. Also, the next hop address for each path must be different. + +.. cfgcmd:: set protocols bgp <asn> parameters default no-ipv4-unicast + + This command allows the user to specify that IPv4 peering is turned off by + default. + +.. cfgcmd:: set protocols bgp <asn> parameters log-neighbor-changes + + This command enable logging neighbor up/down changes and reset reason. + +.. cfgcmd:: set protocols bgp <asn> parameters no-client-to-client-reflection + + This command disables route reflection between route reflector clients. + By default, the clients of a route reflector are not required to be + fully meshed and the routes from a client are reflected to other clients. + However, if the clients are fully meshed, route reflection is not required. + In this case, use the :cfgcmd:`no-client-to-client-reflection` command + to disable client-to-client reflection. + +.. cfgcmd:: set protocols bgp <asn> parameters no-fast-external-failover + + Disable immediate session reset if peer's connected link goes down. + +.. cfgcmd:: set protocols bgp <asn> listen range <prefix> peer-group <name> + + This command is useful if one desires to loosen the requirement for BGP + to have strictly defined neighbors. Specifically what is allowed is for + the local router to listen to a range of IPv4 or IPv6 addresses defined + by a prefix and to accept BGP open messages. When a TCP connection + (and subsequently a BGP open message) from within this range tries to + connect the local router then the local router will respond and connect + with the parameters that are defined within the peer group. One must define + a peer-group for each range that is listed. If no peer-group is defined + then an error will keep you from committing the configuration. + +.. cfgcmd:: set protocols bgp <asn> listen limit <number> + + This command goes hand in hand with the listen range command to limit the + amount of BGP neighbors that are allowed to connect to the local router. + The limit range is 1 to 5000. + +Administrative Distance +^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> parameters distance global + <external|internal|local> <distance> + + This command change distance value of BGP. The arguments are the distance + values for external routes, internal routes and local routes respectively. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols bgp <asn> parameters distance prefix <subnet> + distance <distance> + + This command sets the administrative distance for a particular route. The + distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + + +Timers +^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> timers holdtime <seconds> + + This command specifies hold-time in seconds. The timer range is + 4 to 65535. The default value is 180 second. If you set value to 0 + VyOS will not hold routes. + +.. cfgcmd:: set protocols bgp <asn> timers keepalive <seconds> + + This command specifies keep-alive time in seconds. The timer + can range from 4 to 65535. The default value is 60 second. + + +Route Dampening +^^^^^^^^^^^^^^^ + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in :rfc:`2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + half-life <minutes> + + This command defines the amount of time in minutes after + which a penalty is reduced by half. The timer range is + 10 to 45 minutes. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + re-use <seconds> + + This command defines the accumulated penalty amount at which the + route is re-advertised. The penalty range is 1 to 20000. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + start-suppress-time <seconds> + + This command defines the accumulated penalty amount at which the + route is suppressed. The penalty range is 1 to 20000. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + max-suppress-time <seconds> + + This command defines the maximum time in minutes that a route is + suppressed. The timer range is 1 to 255 minutes. + + +Route Selection Configuration +----------------------------- + +.. cfgcmd:: set protocols bgp <asn> parameters always-compare-med + + This command provides to compare the MED on routes, even when they were + received from different neighbouring ASes. Setting this option makes the + order of preference of routes more defined, and should eliminate MED + induced oscillations. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path confed + + This command specifies that the length of confederation path sets and + sequences should be taken into account during the BGP best path + decision process. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path multipath-relax + + This command specifies that BGP decision process should consider paths + of equal AS_PATH length candidates for multipath computation. Without + the knob, the entire AS_PATH must match for multipath computation. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path ignore + + Ignore AS_PATH length when selecting a route + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath compare-routerid + + Ensure that when comparing routes where both are equal on most metrics, + including local-pref, AS_PATH length, IGP cost, MED, that the tie is + broken based on router-ID. + + If this option is enabled, then the already-selected check, where + already selected eBGP routes are preferred, is skipped. + + If a route has an ORIGINATOR_ID attribute because it has been reflected, + that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer + the route was received from will be used. + + The advantage of this is that the route-selection (at this point) will + be more deterministic. The disadvantage is that a few or even one lowest-ID + router may attract all traffic to otherwise-equal paths because of this + check. It may increase the possibility of MED or IGP oscillation, unless + other measures were taken to avoid these. The exact behaviour will be + sensitive to the iBGP and reflection topology. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath med confed + + This command specifies that BGP considers the MED when comparing routes + originated from different sub-ASs within the confederation to which this + BGP speaker belongs. The default state, where the MED attribute is not + considered. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath med missing-as-worst + + This command specifies that a route with a MED is always considered to be + better than a route without a MED by causing the missing MED attribute to + have a value of infinity. The default state, where the missing MED + attribute is considered to have a value of zero. + +.. cfgcmd:: set protocols bgp <asn> parameters default local-pref + <local-pref value> + + This command specifies the default local preference value. The local + preference range is 0 to 4294967295. + +.. cfgcmd:: set protocols bgp <asn> parameters deterministic-med + + This command provides to compare different MED values that advertised by + neighbours in the same AS for routes selection. When this command is + enabled, routes from the same autonomous system are grouped together, and + the best entries of each group are compared. + +.. cfgcmd:: set protocols bgp <asn> address-family ipv4-unicast network + <prefix> backdoor + + This command allows the router to prefer route to specified prefix learned + via IGP through backdoor link instead of a route to the same prefix learned + via EBGP. + + +Route Filtering Configuration +----------------------------- + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + + - route-map + - filter-list + - prefix-list, distribute-list + +For outbound updates the order of preference is: + + - prefix-list, distribute-list + - filter-list + - route-map + + .. note:: The attributes :cfgcmd:`prefix-list` and :cfgcmd:`distribute-list` + are mutually exclusive, and only one command (distribute-list or + prefix-list) can be applied to each inbound or outbound direction for a + particular neighbor. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> distribute-list <export|import> <number> + + This command applys the access list filters named in <number> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the access list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> prefix-list <export|import> <name> + + This command applys the prfefix list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the prefix list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> route-map <export|import> <name> + + This command applys the route map named in <name> to the specified BGP + neighbor to control and modify routing information that is exchanged + between peers. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the route map are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> filter-list <export|import> <name> + + This command applys the AS path access list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the AS path access list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> capability orf <receive|send> + + This command enables the ORF capability (described in :rfc:`5291`) on the + local router, and enables ORF capability advertisement to the specified BGP + peer. The :cfgcmd:`receive` keyword configures a router to advertise ORF + receive capabilities. The :cfgcmd:`send` keyword configures a router to + advertise ORF send capabilities. To advertise a filter from a sender, you + must create an IP prefix list for the specified BGP peer applied in inbound + derection. + + +BGP Scaling Configuration +------------------------- + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + + - Using BGP route-reflectors + - Using BGP confederation + + +Route Reflector Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in :rfc:`4456` and updated +by :rfc:`7606`. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address> address-family + <ipv4-unicast|ipv6-unicast> route-reflector-client + + This command specifies the given neighbor as route reflector client. + +.. cfgcmd:: set protocols bgp <asn> parameters cluster-id <id> + + This command specifies cluster ID which identifies a collection of route + reflectors and their clients, and is used by route reflectors to avoid + looping. By default cluster ID is set to the BGP router id value, but can be + set to an arbitrary 32-bit value. + + +Confederation Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +:rfc:`5065` + +.. cfgcmd:: set protocols bgp <subasn> parameters confederation identifier + <asn> + + This command specifies a BGP confederation identifier. <asn> is the number + of the autonomous system that internally includes multiple sub-autonomous + systems (a confederation). <subasn> is the number sub-autonomous system + inside <asn>. + +.. cfgcmd:: set protocols bgp <subasn> parameters confederation confederation + peers <nsubasn> + + This command sets other confederations <nsubasn> as members of autonomous + system specified by :cfgcmd:`confederation identifier <asn>`. + + +Operational Mode Commands +========================= + +Show +---- + +.. opcmd:: show <ip|ipv6> bgp + + This command displays all entries in BGP routing table. + +.. code-block:: none + + BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 + Default local pref 100, local AS 65000 + Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + i internal, r RIB-failure, S Stale, R Removed + Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.0/24 10.0.34.4 0 0 65004 i + *> 203.0.113.0/24 10.0.35.5 0 0 65005 i + + Displayed 2 routes and 2 total paths + +.. opcmd:: show <ip|ipv6> bgp <address|prefix> + + This command displays information about the particular entry in the BGP + routing table. + +.. code-block:: none + + BGP routing table entry for 198.51.100.0/24 + Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 + +.. opcmd:: show ip bgp cidr-only + + This command displays routes with classless interdomain routing (CIDR). + +.. opcmd:: show <ip|ipv6> bgp community <value> + + This command displays routes that belong to specified BGP communities. + Valid value is a community number in the range from 1 to 4294967200, + or AA:NN (autonomous system-community number/2-byte number), no-export, + local-as, or no-advertise. + +.. opcmd:: show <ip|ipv6> bgp community-list <name> + + This command displays routes that are permitted by the BGP + community list. + +.. opcmd:: show ip bgp dampened-paths + + This command displays BGP dampened routes. + +.. opcmd:: show ip bgp flap-statistics + + This command displays information about flapping BGP routes. + +.. opcmd:: show ip bgp filter-list <name> + + This command displays BGP routes allowed by by the specified AS Path + access list. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> advertised-routes + + This command displays BGP routes advertised to a neighbor. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> received-routes + + This command displays BGP routes originating from the specified BGP + neighbor before inbound policy is applied. To use this command inbound + soft reconfiguration must be enabled. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> routes + + This command displays BGP received-routes that are accepted after filtering. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> dampened-routes + + This command displays dampened routes received from BGP neighbor. + +.. opcmd:: show <ip|ipv6> bgp regexp <text> + + This command displays information about BGP routes whose AS path + matches the specified regular expression. + +.. opcmd:: show <ip|ipv6> bgp summary + + This command displays the status of all BGP connections. + +.. code-block:: none + + IPv4 Unicast Summary: + BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 + BGP table version 11 + RIB entries 5, using 920 bytes of memory + Peers 4, using 82 KiB of memory + + Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd + 10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 + 10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 + 10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 + 10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + + Total number of neighbors 4 + +Reset +----- + +.. opcmd:: reset <ip|ipv6> bgp <address> [soft [in|out]] + + This command resets BGP connections to the specified neighbor IP address. + With argument :cfgcmd:`soft` this command initiates a soft reset. If + you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both + inbound and outbound soft reconfiguration are triggered. + +.. opcmd:: reset ip bgp all + + This command resets all BGP connections of given router. + +.. opcmd:: reset ip bgp dampening + + This command uses to clear BGP route dampening information and to + unsuppress suppressed routes. + +.. opcmd:: reset ip bgp external + + This command resets all external BGP peers of given router. + +.. opcmd:: reset ip bgp peer-group <name> [soft [in|out]] + + This command resets BGP connections to the specified peer group. + With argument :cfgcmd:`soft` this command initiates a soft reset. If + you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both + inbound and outbound soft reconfiguration are triggered. + + +Configuration Examples +---------------------- + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' + set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' + set protocols bgp 65534 address-family ipv4-unicast network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' + set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' + set protocols bgp 65535 address-family ipv4-unicast network '172.17.0.0/16' + set protocols bgp 65535 parameters router-id '192.168.0.2' + + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route 172.16.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route 172.17.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' + set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast + set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' + set protocols bgp 65534 parameters router-id '10.1.1.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' + set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast + set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' + set protocols bgp 65535 parameters router-id '10.1.1.2' + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route6 2001:db8:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route6 2001:db8:2::/48 blackhole distance '254' + +Route Filter +^^^^^^^^^^^^ + +Route filter can be applied using a route-map: + +**Node1:** + +.. code-block:: none + + set policy prefix-list AS65535-IN rule 10 action 'permit' + set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' + set policy prefix-list AS65535-OUT rule 10 action 'deny' + set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' + set policy prefix-list6 AS65535-IN rule 10 action 'permit' + set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' + set policy prefix-list6 AS65535-OUT rule 10 action 'deny' + set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + set policy route-map AS65535-IN rule 10 action 'permit' + set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 20 action 'deny' + set policy route-map AS65535-OUT rule 10 action 'deny' + set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 20 action 'permit' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' + +**Node2:** + +.. code-block:: none + + set policy prefix-list AS65534-IN rule 10 action 'permit' + set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' + set policy prefix-list AS65534-OUT rule 10 action 'deny' + set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' + set policy prefix-list6 AS65534-IN rule 10 action 'permit' + set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' + set policy prefix-list6 AS65534-OUT rule 10 action 'deny' + set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + set policy route-map AS65534-IN rule 10 action 'permit' + set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 20 action 'deny' + set policy route-map AS65534-OUT rule 10 action 'deny' + set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 20 action 'permit' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/igmp-proxy.disable b/docs/configuration/protocols/igmp-proxy.disable new file mode 100644 index 00000000..cce5f948 --- /dev/null +++ b/docs/configuration/protocols/igmp-proxy.disable @@ -0,0 +1,2 @@ +igmp-proxy +##########
\ No newline at end of file diff --git a/docs/routing/multicast.rst b/docs/configuration/protocols/igmp.rst index d20d8e31..7109deb6 100644 --- a/docs/routing/multicast.rst +++ b/docs/configuration/protocols/igmp.rst @@ -7,7 +7,6 @@ Multicast VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**, **IGMP** and **IGMP-Proxy**. - ************ PIM and IGMP ************ @@ -16,7 +15,7 @@ PIM (Protocol Independent Multicast) must be configured in every interface of every participating router. Every router must also have the location of the Rendevouz Point manually configured. Then, unidirectional shared trees rooted at the Rendevouz Point will -automatically be built for multicast distribution. +automatically be built for multicast distribution. Traffic from multicast sources will go to the Rendezvous Point, and receivers will pull it from a shared tree using IGMP (Internet Group @@ -24,7 +23,7 @@ Management Protocol). Multicast receivers will talk IGMP to their local router, so, besides having PIM configured in every router, IGMP must also be configured in -any router where there could be a multicast receiver locally connected. +any router where there could be a multicast receiver locally connected. VyOS supports both IGMP version 2 and version 3 (which allows source-specific multicast). @@ -54,7 +53,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth1 set protocols pim interface eth2 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + **Router 3** .. code-block:: none @@ -69,7 +68,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth0 set protocols pim interface eth1 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + **Router 2** .. code-block:: none @@ -81,7 +80,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth1 set protocols pim interface eth2 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + @@ -97,13 +96,14 @@ These are the commands for a basic setup. can communicate with PIM neighbors. -.. cfgcmd:: set protocols pim rp address <address> group <multicast-address/mask-bits> +.. cfgcmd:: set protocols pim rp address <address> group + <multicast-address/mask-bits> Use this comand to manually configure a Rendevouz Point for PIM so that join messages can be sent there. Set the Rendevouz Point address and the matching prefix of group ranges covered. These values must be shared with every router participating in the PIM network. - + .. cfgcmd:: set protocols igmp interface eth1 @@ -141,7 +141,8 @@ You can also tune multicast with the following commands. platforms cannot see data flowing in better than 30 second chunks. -.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address> source <IP-address> +.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address> + source <IP-address> Use this command to allow the selected interface join a multicast group defining the multicast address you want to join and the source @@ -154,7 +155,8 @@ You can also tune multicast with the following commands. host query interval (1-1800) in seconds that PIM will use. -.. cfgcmd:: set protocols igmp interface <interface query-max-response-time <deciseconds> +.. cfgcmd:: set protocols igmp interface <interface query-max-response-time + <deciseconds> Use this command to configure in the selected interface the IGMP query response timeout value (10-250) in deciseconds. If a report is @@ -163,7 +165,7 @@ You can also tune multicast with the following commands. timed out. -.. cfgcmd:: set protocols igmp interface <interface> version <version-number> +.. cfgcmd:: set protocols igmp interface <interface> version <version-number> Use this command to define in the selected interface whether you choose IGMP version 2 or 3. The default value is 3. @@ -181,7 +183,8 @@ upstream interface, and one or more downstream interfaces. Configuration ============= -.. cfgcmd:: set protocols igmp-proxy interface <interface> role <upstream | downstream> +.. cfgcmd:: set protocols igmp-proxy interface <interface> role + <upstream | downstream> * **upstream:** The upstream network interface is the outgoing interface which is responsible for communicating to available multicast data sources. diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst new file mode 100644 index 00000000..c302d6a9 --- /dev/null +++ b/docs/configuration/protocols/index.rst @@ -0,0 +1,18 @@ +######### +Protocols +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bfd + bgp + igmp + isis + mpls + ospf + rip + rpki + static diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst new file mode 100644 index 00000000..05a851f1 --- /dev/null +++ b/docs/configuration/protocols/isis.rst @@ -0,0 +1,305 @@ +.. include:: /_include/need_improvement.txt + +.. _isis: + +##### +IS-IS +##### + +:abbr:`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway routing protocol which is described in ISO10589, +:rfc:`1195`, :rfc:`5308`. Like OSPF, IS-IS runs the Dijkstra shortest-path +first (SPF) algorithm to create a database of the network’s topology and, +from that database, to determine the best (that is, shortest) path to a +destination. The routers exchange topology information with their nearest +neighbors. IS-IS runs directly on the data link layer (Layer 2). IS-IS +addresses are called :abbr:`NETs (Network Entity Titles)` and can be +8 to 20 bytes long, but are generally 10 bytes long. + +For example :abbr:`NET (Network Entity Title)` + +.. code-block:: none + + 49.0001.1921.6800.1002.00 + +The IS-IS address consists of three parts: + + :abbr:`AFI (Address family authority identifier)` + ``49`` The AFI value 49 is what IS-IS uses for private addressing. + + Area identifier: + ``0001`` IS-IS area number (Area1) + + System identifier: + ``1921.6800.1002`` For system idetifier we recommend to use IP address or + MAC address of the router. + + NET selector: + ``00`` Must always be 00, to indicate "this system". + + +General Configuration +--------------------- + +.. cfgcmd:: set protocols isis <name> net <network-entity-title> + + This command enables the ISIS process by specifying the ISIS domain with + ‘name’. ISIS implementation does not yet support multiple ISIS processes + but you must specify the name of ISIS process. This commad also sets + network entity title (NET) provided in ISO format. + +.. cfgcmd:: set protocols isis <name> interface <interface> + + This command activates ISIS adjacency on this interface. Note that the name + of ISIS instance must be the same as the one used to configure the ISIS + process. + +.. cfgcmd:: set protocols isis <name> dynamic-hostname + + This command enables support for dynamic hostname. Dynamic hostname mapping + determined as described in :rfc:`2763`, Dynamic Hostname Exchange Mechanism + for IS-IS. + +.. cfgcmd:: set protocols isis <name> level <level-1|level-1-2|level-2> + + This command defines the ISIS router behavior: + + **level-1** Act as a station router only. + **level-1-2** Act as both a station router and an area router. + **level-2-only** Act as an area router only. + +.. cfgcmd:: set protocols isis <name> lsp-mtu <size> + + This command configures the maximum size of generated LSPs, in bytes. The + size range is 128 to 4352. + +.. cfgcmd:: set protocols isis <name> metric-style <narrow|transition|wide> + + This command sets old-style (ISO 10589) or new-style packet formats: + + **narrow** Use old style of TLVs with narrow metric. + **transition** Send and accept both styles of TLVs during transition. + **wide** Use new style of TLVs to carry wider metric. + +.. cfgcmd:: set protocols isis <name> purge-originator + + This command enables :rfc:`6232` purge originator identification. Enable + purge originator identification (POI) by adding the type, length and value + (TLV) with the Intermediate System (IS) identification to the LSPs that do + not contain POI information. If an IS generates a purge, VyOS adds this TLV + with the system ID of the IS to the purge. + +.. cfgcmd:: set protocols isis <name> set-attached-bit + + This command sets ATT bit to 1 in Level1 LSPs. It is described in :rfc:`3787`. + +.. cfgcmd:: set protocols isis <name> set-overload-bit + + This command sets overload bit to avoid any transit traffic through this + router. It is described in :rfc:`3787`. + +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-1 + + This command will generate a default-route in L1 database. + +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-2 + + This command will generate a default-route in L2 database. + + +Interfaces Configuration +------------------------ + +.. cfgcmd:: set protocols isis <name> interface <interface> circuit-type + <level-1|level-1-2|level-2-only> + + This command specifies circuit type for interface: + + **level-1** Level-1 only adjacencies are formed. + **level-1-2** Level-1-2 adjacencies are formed + **level-2-only** Level-2 only adjacencies are formed + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-interval + <seconds> + + This command sets hello interval in seconds on a given interface. + The range is 1 to 600. + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-multiplier + <seconds> + + This command sets multiplier for hello holding time on a given + interface. The range is 2 to 100. + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-padding + + This command configures padding on hello packets to accommodate asymmetrical + maximum transfer units (MTUs) from different hosts as described in + :rfc:`3719`. This helps to prevent a premature adjacency Up state when one + routing device’s MTU does not meet the requirements to establish the + adjacency. + +.. cfgcmd:: set protocols isis <name> interface <interface> metric <metric> + + This command set default metric for circuit. The metric range is 1 to + 16777215 (Max value depend if metric support narrow or wide value). + +.. cfgcmd:: set protocols isis <name> interface <interface> network + point-to-point + + This command specifies network type to ‘Point-to-Point’. The default network + type is broadcast. + +.. cfgcmd:: set protocols isis <name> interface <interface> passive + + This command configures the passive mode for this interface. + +.. cfgcmd:: set protocols isis <name> interface <interface> password + plaintext-password <text> + + This command configures the authentication password for the interface. + +.. cfgcmd:: set protocols isis <name> interface <interface> priority <number> + + This command sets priority for the interface for + :abbr:`DIS (Designated Intermediate System)` election. The priority + range is 0 to 127. + +.. cfgcmd:: set protocols isis <name> interface <interface> psnp-interval + <number> + + This command sets PSNP interval in seconds. The interval range is 0 + to 127. + +.. cfgcmd:: set protocols isis <name> interface <interface> + no-three-way-handshake + + This command disables Three-Way Handshake for P2P adjacencies which + described in :rfc:`5303`. Three-Way Handshake is enabled by default. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> level-1 + + This command redistributes routing information from the given route source + into the ISIS database as Level-1. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> level-2 + + This command redistributes routing information from the given route source + into the ISIS database as Level-2. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> + <level-1|level-2> metric <number> + + This command specifies metric for redistributed routes from the given route + source. There are six modes available for route source: bgp, connected, + kernel, ospf, rip, static. The metric range is 1 to 16777215. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> + <level-1|level-2> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are six modes available for route source: + bgp, connected, kernel, ospf, rip, static. + + +Timers Configuration +-------------------- + +.. cfgcmd:: set protocols isis <name> lsp-gen-interval <seconds> + + This command sets minimum interval in seconds between regenerating same + LSP. The interval range is 1 to 120. + +.. cfgcmd:: set protocols isis <name> lsp-refresh-interval <seconds> + + This command sets LSP refresh interval in seconds. IS-IS generates LSPs + when the state of a link changes. However, to ensure that routing + databases on all routers remain converged, LSPs in stable networks are + generated on a regular basis even though there has been no change to + the state of the links. The interval range is 1 to 65235. The default + value is 900 seconds. + +.. cfgcmd:: set protocols isis <name> max-lsp-lifetime <seconds> + + This command sets LSP maximum LSP lifetime in seconds. The interval range + is 350 to 65535. LSPs remain in a database for 1200 seconds by default. + If they are not refreshed by that time, they are deleted. You can change + the LSP refresh interval or the LSP lifetime. The LSP refresh interval + should be less than the LSP lifetime or else LSPs will time out before + they are refreshed. + +.. cfgcmd:: set protocols isis <name> spf-interval <seconds> + + This command sets minimum interval between consecutive SPF calculations in + seconds.The interval range is 1 to 120. + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf holddown <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf init-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf long-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf short-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf time-to-learn + <milliseconds> + + This commands specifies the Finite State Machine (FSM) intended to + control the timing of the execution of SPF calculations in response + to IGP events. The process described in :rfc:`8405`. + + +Configuration Example +--------------------- + +Simple IS-IS configuration using 2 nodes and redistributing connected +interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces dummy dum0 address '203.0.113.1/24' + set interfaces ethernet eth1 address '192.0.2.1/24' + + set policy prefix-list EXPORT-ISIS rule 10 action 'permit' + set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' + set policy route-map EXPORT-ISIS rule 10 action 'permit' + set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + + set protocols isis FOO interface eth1 + set protocols isis FOO net '49.0001.1921.6800.1002.00' + set protocols isis FOO redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' + +**Node 2:** + +.. code-block:: none + + set interfaces ethernet eth1 address '192.0.2.2/24' + + set protocols isis FOO interface eth1 + set protocols isis FOO net '49.0001.1921.6800.2002.00' + +Show ip routes on Node2: + +.. code-block:: none + + vyos@r2:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/mpls.rst new file mode 100644 index 00000000..312a0df2 --- /dev/null +++ b/docs/configuration/protocols/mpls.rst @@ -0,0 +1,253 @@ +.. _mpls: + +#### +MPLS +#### + +:abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +`Wikipedia (MPLS)`_. + +.. note:: MPLS support in VyOS is not finished yet, and therefore its + functionality is limited. Currently there is no support for MPLS enabled VPN + services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present + as the underlying routing stack (FRR) does not implement it. Currently VyOS + can be configured as a label switched router (MPLS P router), in both + penultimate and ultimate hop popping operations. + +Label Distribution Protocol +=========================== + +The :abbr:`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. + +:abbr:`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +Configuration Options +===================== + +.. cfgcmd:: set protocols mpls ldp interface <interface> + + Use this command to enable LDP, and enable MPLS processing on the interface + you define. + +.. cfgcmd:: set protocols mpls ldp router-id <address> + + Use this command to configure the IP address used as the LDP router-id of the + local device. + +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address <address> +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address <address> + + Use this command to set the IPv4 or IPv6 transport-address used by LDP. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> password <password> + + Use this command to configure authentication for LDP peers. Set the + IP address of the LDP peer and a password that should be shared in + order to become neighbors. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> session-holdtime <seconds> + + Use this command to configure a specific session hold time for LDP peers. + Set the IP address of the LDP peer and a session hold time that should be + configured for it. You may have to reset the neighbor for this to work. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> ttl-security + <disable | hop count> + + Use this command to enable, disable, or specify hop count for TTL security + for LDP peers. By default the value is set to 255 (or max TTL). + +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters. + +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds> + + Use this command if you would like to set the TCP session hold time intervals. + +.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 + <access list number> + + Use these commands to control the importing of forwarding equivalence classes + (FECs) for LDP from neighbors. This would be useful for example on only + accepting the labeled routes that are needed and not ones that are not + needed, such as accepting loopback interfaces and rejecting all others. + +.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 + <access list number> + + Use these commands to control the exporting of forwarding equivalence classes + (FECs) for LDP to neighbors. This would be useful for example on only + announcing the labeled routes that are needed and not ones that are not + needed, such as announcing loopback interfaces and no others. + +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a + label of 0 for explicit null operations. + +.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 + <access list number> + + Use this command if you would like to control the local FEC allocations for + LDP. A good example would be for your local router to not allocate a label for + everything. Just a label for what it's useful. A good example would be just a + loopback label. + +.. cfgcmd:: set protocols mpls ldp parameters cisco-interop-tlv + + Use this command to use a Cisco non-compliant format to send and interpret + the Dual-Stack capability TLV for IPv6 LDP communications. This is related to + :rfc:`7552`. + +.. cfgcmd:: set protocols mpls ldp parameters ordered-control + + Use this command to use ordered label distribution control mode. FRR + by default uses independent label distribution control mode for label + distribution. This is related to :rfc:`5036`. + +.. cfgcmd:: set protocols mpls ldp parameters transport-prefer-ipv4 + + Use this command to prefer IPv4 for TCP peer transport connection for LDP + when both an IPv4 and IPv6 LDP address are configured on the same interface. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 enable +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 enable + + Use this command to enable targeted LDP sessions to the local router. The + router will then respond to any sessions that are trying to connect to it that + are not a link local type of TCP connection. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 address <address> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 address <address> + + Use this command to enable the local router to try and connect with a targeted + LDP session to another router. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-interval + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-interval + <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters for the targeted LDP neighbors. + + +Sample configuration to setup LDP on VyOS +----------------------------------------- + +.. code-block:: none + + set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback + set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network + set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF + set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to + set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network + set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity + set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP + set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network + set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses + + +Operational Mode Commands +========================= + +When LDP is working, you will be able to see label information in the outcome +of ``show ip route``. Besides that information, there are also specific *show* +commands for LDP: + +Show +---- + +.. opcmd:: show mpls ldp binding + + Use this command to see the Label Information Base. + +.. opcmd:: show mpls ldp discovery + + Use this command to see discovery hello information + +.. opcmd:: show mpls ldp interface + + Use this command to see LDP interface information + +.. opcmd:: show mpls ldp neighbor + + Use this command to see LDP neighbor information + +.. opcmd:: show mpls ldp neighbor detail + + Use this command to see detailed LDP neighbor information + +Reset +----- + +.. opcmd:: reset mpls ldp neighbor <IPv4 or IPv6 address> + + Use this command to reset an LDP neighbor/TCP session that is established + + +.. stop_vyoslinter + +.. _`Wikipedia (MPLS)`: https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst new file mode 100644 index 00000000..e1957cec --- /dev/null +++ b/docs/configuration/protocols/ospf.rst @@ -0,0 +1,1019 @@ +.. _routing-ospf: + +#### +OSPF +#### + +:abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in :rfc:`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in :rfc:`5340` +(2008). OSPF supports the :abbr:`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +************* +OSPFv2 (IPv4) +************* + +Configuration +============= + +General +------- + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +.. cfgcmd:: set protocols ospf area <number> network <A.B.C.D/M> + + This command specifies the OSPF enabled interface(s). If the interface has + an address from defined range then the command enables OSPF on this + interface so router can provide network information to the other ospf + routers via this interface. + + This command is also used to enable the OSPF process. The area number can be + specified in decimal notation in the range from 0 to 4294967295. Or it + can be specified in dotted decimal notation similar to ip address. + +.. cfgcmd:: set protocols ospf auto-cost reference-bandwidth <number> + + This command sets the reference bandwidth for cost calculations, where + bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The + default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will + have a cost of 1. Cost of lower bandwidth links will be scaled with + reference to this cost). + +.. cfgcmd:: set protocols ospf parameters router-id <rid> + + This command sets the router-ID of the OSPF process. The router-ID may be an + IP address of the router, but need not be – it can be any arbitrary 32bit + number. However it MUST be unique within the entire OSPF domain to the OSPF + speaker – bad things will happen if multiple OSPF speakers are configured + with the same router-ID! + + +Optional +-------- + +.. cfgcmd:: set protocols ospf default-information originate [always] + [metric <number>] [metric-type <1|2>] [route-map <name>] + + Originate an AS-External (type-5) LSA describing a default route into all + external-routing capable areas, of the specified metric and metric type. + If the :cfgcmd:`always` keyword is given then the default is always + advertised, even when there is no default present in the routing table. + The argument :cfgcmd:`route-map` specifies to advertise the default route + if the route map is satisfied. + +.. cfgcmd:: set protocols ospf distance global <distance> + + This command change distance value of OSPF globally. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols ospf distance ospf <external|inter-area|intra-area> + <distance> + + This command change distance value of OSPF. The arguments are the distance + values for external routes, inter-area routes and intra-area routes + respectively. The distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols ospf log-adjacency-changes [detail] + + This command allows to log changes in adjacency. With the optional + :cfgcmd:`detail` argument, all changes in adjacency status are shown. + Without :cfgcmd:`detail`, only changes to full or regressions are shown. + +.. cfgcmd:: set protocols ospf max-metric router-lsa + <administrative|on-shutdown <seconds>|on-startup <seconds>> + + This enables :rfc:`3137` support, where the OSPF process describes its + transit links in its router-LSA as having infinite distance so that other + routers will avoid calculating transit paths through the router while + still being able to reach networks through the router. + + This support may be enabled administratively (and indefinitely) with the + :cfgcmd:`administrative` command. It may also be enabled conditionally. + Conditional enabling of max-metric router-lsas can be for a period of + seconds after startup with the :cfgcmd:`on-startup <seconds>` command + and/or for a period of seconds prior to shutdown with the + :cfgcmd:`on-shutdown <seconds>` command. The time range is 5 to 86400. + +.. cfgcmd:: set protocols ospf parameters abr-type + <cisco|ibm|shortcut|standard> + + This command selects ABR model. OSPF router supports four ABR models: + + **cisco** – a router will be considered as ABR if it has several configured + links to the networks in different areas one of which is a backbone area. + Moreover, the link to the backbone area should be active (working). + **ibm** – identical to "cisco" model but in this case a backbone area link + may not be active. + **standard** – router has several active links to different areas. + **shortcut** – identical to "standard" but in this model a router is + allowed to use a connected areas topology without involving a backbone + area for inter-area connections. + + Detailed information about "cisco" and "ibm" models differences can be + found in :rfc:`3509`. A "shortcut" model allows ABR to create routes + between areas based on the topology of the areas connected to this router + but not using a backbone area in case if non-backbone route will be + cheaper. For more information about "shortcut" model, + see :t:`ospf-shortcut-abr-02.txt` + +.. cfgcmd:: set protocols ospf parameters rfc1583-compatibility + + :rfc:`2328`, the successor to :rfc:`1583`, suggests according to section + G.2 (changes) in section 16.4.1 a change to the path preference algorithm + that prevents possible routing loops that were possible in the old version + of OSPFv2. More specifically it demands that inter-area paths and + intra-area backbone path are now of equal preference but still both + preferred to external paths. + + This command should NOT be set normally. + +.. cfgcmd:: set protocols ospf passive-interface <interface> + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). + +.. cfgcmd:: set protocols ospf passive-interface default + + This command specifies all interfaces as passive by default. Because this + command changes the configuration logic to a default passive; therefore, + interfaces where router adjacencies are expected need to be configured + with the :cfgcmd:`passive-interface-exclude` command. + +.. cfgcmd:: set protocols ospf passive-interface-exclude <interface> + + This command allows exclude interface from passive state. This command is + used if the command :cfgcmd:`passive-interface default` was configured. + +.. cfgcmd:: set protocols ospf refresh timers <seconds> + + The router automatically updates link-state information with its neighbors. + Only an obsolete information is updated which age has exceeded a specific + threshold. This parameter changes a threshold value, which by default is + 1800 seconds (half an hour). The value is applied to the whole OSPF router. + The timer range is 10 to 1800. + +.. cfgcmd:: set protocols ospf timers throttle spf + <delay|initial-holdtime|max-holdtime> <seconds> + + This command sets the initial delay, the initial-holdtime and the + maximum-holdtime between when SPF is calculated and the event which + triggered the calculation. The times are specified in milliseconds and must + be in the range of 0 to 600000 milliseconds. :cfgcmd:`delay` sets the + initial SPF schedule delay in milliseconds. The default value is 200 ms. + :cfgcmd:`initial-holdtime` sets the minimum hold time between two + consecutive SPF calculations. The default value is 1000 ms. + :cfgcmd:`max-holdtime` sets the maximum wait time between two + consecutive SPF calculations. The default value is 10000 ms. + + +Area Configuration +------------------ + +.. cfgcmd:: set protocols ospf area <number> area-type stub + + This command specifies the area to be a Stub Area. That is, an area where + no router originates routes external to OSPF and hence an area where all + external routes are via the ABR(s). Hence, ABRs for such an area do not + need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into + the area. They need only pass Network-Summary (type-3) LSAs into such an + area, along with a default-route summary. + +.. cfgcmd:: set protocols ospf area <number> area-type stub no-summary + + This command specifies the area to be a Totally Stub Area. In addition to + stub area limitations this area type prevents an ABR from injecting + Network-Summary (type-3) LSAs into the specified stub area. Only default + summary route is allowed. + +.. cfgcmd:: set protocols ospf area <number> area-type stub default-cost + <number> + + This command sets the cost of default-summary LSAs announced to stubby + areas. The cost range is 0 to 16777215. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa + + This command specifies the area to be a Not So Stubby Area. External + routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs + are similar to Type-5 AS-external LSAs, except that they can only be + flooded into the NSSA. In order to further propagate the NSSA external + information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA + by the NSSA ABR. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa no-summary + + This command specifies the area to be a NSSA Totally Stub Area. ABRs for + such an area do not need to pass Network-Summary (type-3) LSAs (except the + default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs + (type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA + ABR are allowed. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa default-cost + <number> + + This command sets the default cost of LSAs announced to NSSA areas. + The cost range is 0 to 16777215. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa translate + <always|candidate|never> + + Specifies whether this NSSA border router will unconditionally translate + Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are + translated into Type-5 LSAs regardless of the translator state of other + NSSA border routers. When role is Candidate, this router participates in + the translator election to determine if it will perform the translations + duties. When role is Never, this router will never translate Type-7 LSAs + into Type-5 LSAs. + +.. cfgcmd:: set protocols ospf area <number> authentication plaintext-password + + This command specifies that simple password authentication should be used + for the given area. The password must also be configured on a per-interface + basis. + +.. cfgcmd:: set protocols ospf area <number> authentication md5 + + This command specify that OSPF packets must be authenticated with MD5 HMACs + within the given area. Keying material must also be configured on a + per-interface basis. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> [cost <number>] + + This command summarizes intra area paths from specified area into one + summary-LSA (Type-3) announced to other areas. This command can be used + only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) + (i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) + can’t be summarized - their scope is AS. The optional argument + :cfgcmd:`cost` specifies the aggregated link metric. The metric range is 0 + to 16777215. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. + This command makes sense in ABR only. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> substitute + <E.F.G.H/M> + + One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into + backbone area if defined area contains at least one intra-area network + (i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>. + This command makes sense in ABR only. + +.. cfgcmd:: set protocols ospf area <number> shortcut <default|disable|enable> + + This parameter allows to "shortcut" routes (non-backbone) for inter-area + routes. There are three modes available for routes shortcutting: + + **default** – this area will be used for shortcutting only if ABR does not + have a link to the backbone area or this link was lost. + **enable** – the area will be used for shortcutting every time the route + that goes through it is cheaper. + **disable** – this area is never used by ABR for routes shortcutting. + +.. cfgcmd:: set protocols ospf area <number> virtual-link <A.B.C.D> + + Provides a backbone area coherence by virtual link establishment. + + In general, OSPF protocol requires a backbone area (area 0) to be coherent + and fully connected. I.e. any backbone area router must have a route to any + other backbone area router. Moreover, every ABR must have a link to + backbone area. However, it is not always possible to have a physical link + to a backbone area. In this case between two ABR (one of them has a link to + the backbone area) in the area (not stub area) a virtual link is organized. + + <number> – area identifier through which a virtual link goes. + <A.B.C.D> – ABR router-id with which a virtual link is established. Virtual + link must be configured on both routers. + + Formally, a virtual link looks like a point-to-point network connecting two + ABR from one area one of which physically connected to a backbone area. + This pseudo-network is considered to belong to a backbone area. + + +Interface Configuration +----------------------- + +.. cfgcmd:: set protocols ospf interface <interface> authentication + plaintext-password <text> + + This command sets OSPF authentication key to a simple password. After + setting, all OSPF packets are authenticated. Key has length up to 8 chars. + + Simple text password authentication is insecure and deprecated in favour of + MD5 HMAC authentication. + +.. cfgcmd:: set protocols ospf interface <interface> authentication md5 + key-id <id> md5-key <text> + + This command specifys that MD5 HMAC authentication must be used on this + interface. It sets OSPF authentication key to a cryptographic password. + Key-id identifies secret key used to create the message digest. This ID + is part of the protocol and must be consistent across routers on a link. + The key can be long up to 16 chars (larger strings will be truncated), + and is associated with the given key-id. + +.. cfgcmd:: set protocols ospf interface <interface> bandwidth <number> + + This command sets the interface bandwidth for cost calculations, where + bandwidth can be in range from 1 to 100000, specified in Mbits/s. + +.. cfgcmd:: set protocols ospf interface <interface> cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> dead-interval <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> hello-multiplier <number> + + The hello-multiplier specifies how many Hellos to send per second, from 1 + (every second) to 10 (every 100ms). Thus one can have 1s convergence time + for OSPF. If this form is specified, then the hello-interval advertised in + Hello packets is set to 0 and the hello-interval on received Hello packets + is not checked, thus the hello-multiplier need NOT be the same across + multiple routers on a common link. + +.. cfgcmd:: set protocols ospf interface <interface> hello-interval <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> bfd + + This command enables :abbr:`BFD (Bidirectional Forwarding Detection)` on + this OSPF link interface. + +.. cfgcmd:: set protocols ospf interface <interface> mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. Thus, + use of this command allows the OSPF adjacency to reach the FULL state even + though there is an interface MTU mismatch between two OSPF routers. + +.. cfgcmd:: set protocols ospf interface <interface> network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **non-broadcast** – address distribution in NBMA networks topology. + **point-to-multipoint** – address distribution in point-to-multipoint + networks. + **point-to-point** – address distribution in point-to-point networks. + +.. cfgcmd:: set protocols ospf interface <interface> priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become + Designated Router. The default value is 1. The interval range is 0 to 255. + +.. cfgcmd:: set protocols ospf interface <interface> retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> transmit-delay <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. + + +Manual Neighbor Configuration +----------------------------- + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> + + This command specifies the IP address of the neighboring device. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> poll-interval <seconds> + + This command specifies the length of time, in seconds, before the routing + device sends hello packets out of the interface before it establishes + adjacency with a neighbor. The range is 1 to 65535 seconds. The default + value is 60 seconds. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> priority <number> + + This command specifies the router priority value of the nonbroadcast + neighbor associated with the IP address specified. The default is 0. + This keyword does not apply to point-to-multipoint interfaces. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols ospf redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPF process. There are five modes available for route source: bgp, + connected, kernel, rip, static. + +.. cfgcmd:: set protocols ospf default-metric <number> + + This command specifies the default metric value of redistributed routes. + The metric range is 0 to 16777214. + +.. cfgcmd:: set protocols ospf redistribute <route source> metric <number> + + This command specifies metric for redistributed routes from the given + route source. There are five modes available for route source: bgp, + connected, kernel, rip, static. The metric range is 1 to 16777214. + +.. cfgcmd:: set protocols ospf redistribute <route source> metric-type <1|2> + + This command specifies metric type for redistributed routes. Difference + between two metric types that metric type 1 is a metric which is + "commensurable" with inner OSPF links. When calculating a metric to the + external destination, the full path metric is calculated as a metric sum + path of a router which had advertised this link plus the link metric. + Thus, a route with the least summary metric will be selected. If external + link is advertised with metric type 2 the path is selected which lies + through the router which advertised this link with the least metric + despite of the fact that internal path to this router is longer (with more + cost). However, if two routers advertised an external link and with metric + type 2 the preference is given to the path which lies through the router + with a shorter internal path. If two different routers advertised two + links to the same external destimation but with different metric type, + metric type 1 is preferred. If type of a metric left undefined the router + will consider these external links to have a default metric type 2. + +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are five modes available for route source: + bgp, connected, kernel, rip, static. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ip ospf neighbor + + This command displays the neighbors status. + +.. code-block:: none + + Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL + 10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 + 10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 + +.. opcmd:: show ip ospf neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. + +.. code-block:: none + + Neighbor 10.0.13.1, interface address 10.0.13.1 + In the area 0.0.0.0 via interface eth0 + Neighbor priority is 1, State is Full, 5 state changes + Most recent state change statistics: + Progressive change 11m55s ago + DR is 10.0.13.1, BDR is 10.0.13.3 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 34.854s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + + Neighbor 10.0.23.2, interface address 10.0.23.2 + In the area 0.0.0.1 via interface eth1 + Neighbor priority is 1, State is Full, 4 state changes + Most recent state change statistics: + Progressive change 41.193s ago + DR is 10.0.23.3, BDR is 10.0.23.2 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 35.661s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + +.. opcmd:: show ip ospf neighbor <A.B.C.D> + + This command displays the neighbors information in a detailed form for a + neighbor whose IP address is specified. + +.. opcmd:: show ip ospf neighbor <intname> + + This command displays the neighbors status for a neighbor on the specified + interface. + +.. opcmd:: show ip ospf interface [<intname>] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. + +.. code-block:: none + + eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 + eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 + +.. opcmd:: show ip ospf route + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. + +.. code-block:: none + + ============ OSPF network routing table ============ + N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 + N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 + N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + + ============ OSPF router routing table ============= + R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 + R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + + ============ OSPF external routing table =========== + N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 + +The table consists of following data: + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "<metric of the router which advertised the link>/<link metric>" format. + +.. opcmd:: show ip ospf border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. + +.. opcmd:: show ip ospf database + + This command displays a summary table with a database contents (LSA). + +.. code-block:: none + + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum Link count + 10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 + 10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 + 10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum + 10.0.13.1 10.0.13.1 994 0x80000003 0x30bb + 10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum Route + 10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 + 10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + + Link ID ADV Router Age Seq# CkSum Route + 172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] + +.. opcmd:: show ip ospf database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link advertisement + type. + + The type can be the following: + asbr-summary, external, network, nssa-external, opaque-area, opaque-as, + opaque-link, router, summary. + + [A.B.C.D] – link-state-id. With this specified the command displays portion + of the network environment that is being described by the advertisement. + The value entered depends on the advertisement’s LS type. It must be + entered in the form of an IP address. + + :cfgcmd:`adv-router <A.B.C.D>` – router id, which link advertisements need + to be reviewed. + + :cfgcmd:`self-originate` displays only self-originated LSAs from the local + router. + +.. code-block:: none + + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + + LS age: 1213 + Options: 0x2 : *|-|-|-|-|-|E|- + LS Flags: 0x3 + Flags: 0x0 + LS Type: router-LSA + Link State ID: 10.0.13.1 + Advertising Router: 10.0.13.1 + LS Seq Number: 80000009 + Checksum: 0xd119 + Length: 36 + + Number of Links: 1 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 10.0.13.1 + (Link Data) Router Interface address: 10.0.13.1 + Number of TOS metrics: 0 + TOS 0 Metric: 1 + +.. opcmd:: show ip ospf database max-age + + This command displays LSAs in MaxAge list. + + +Configuration Example +--------------------- + +Below you can see a typical configuration using 2 nodes, redistribute loopback +address and the node 1 sending the default route: + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf default-information originate always + set protocols ospf default-information originate metric 10 + set protocols ospf default-information originate metric-type 2 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.1.1.1 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.2.2.2/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.2.2.2 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + + +************* +OSPFv3 (IPv6) +************* + +Configuration +============= + +General +------- + +VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 +process starts when the first ospf enabled interface is configured. + +.. cfgcmd:: set protocols ospfv3 area <number> interface <interface> + + This command specifies the OSPFv3 enabled interface. This command is also + used to enable the OSPF process. The area number can be specified in + decimal notation in the range from 0 to 4294967295. Or it can be specified + in dotted decimal notation similar to ip address. + +.. cfgcmd:: set protocols ospfv3 parameters router-id <rid> + + This command sets the router-ID of the OSPFv3 process. The router-ID may be + an IP address of the router, but need not be – it can be any arbitrary + 32bit number. However it MUST be unique within the entire OSPFv3 domain to + the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are + configured with the same router-ID! + + +Optional +-------- + +.. cfgcmd:: set protocols ospfv3 distance global <distance> + + This command change distance value of OSPFv3 globally. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols ospfv3 distance ospfv3 + <external|inter-area|intra-area> <distance> + + This command change distance value of OSPFv3. The arguments are the + distance values for external routes, inter-area routes and intra-area + routes respectively. The distance range is 1 to 255. + + +Area Configuration +------------------ + +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> + + This command summarizes intra area paths from specified area into one + Type-3 Inter-Area Prefix LSA announced to other areas. This command can be + used only in ABR. + +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. This + command makes sense in ABR only. + + +Interface Configuration +----------------------- + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 dead-interval + <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 hello-interval + <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. + Thus, use of this command allows the OSPF adjacency to reach the FULL + state even though there is an interface MTU mismatch between two OSPF + routers. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **point-to-point** – address distribution in point-to-point networks. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become Designated + Router. The default value is 1. The interval range is 0 to 255. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 passive + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 transmit-delay + <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols ospfv3 redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPFv3 process. There are five modes available for route source: + bgp, connected, kernel, ripng, static. + +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + given route source. There are five modes available for route source: bgp, + connected, kernel, ripng, static. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ipv6 ospfv3 neighbor + + This command displays the neighbors status. + +.. opcmd:: show ipv6 ospfv3 neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. + +.. opcmd:: show ipv6 ospfv3 neighbor <A.B.C.D> + + This command displays the neighbors information in a detailed form for + a neighbor whose IP address is specified. + +.. opcmd:: show ipv6 ospfv3 neighbor <intname> + + This command displays the neighbors status for a neighbor on the specified + interface. + +.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<intname> [prefix]] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. Whith the argument + :cfgcmd:`prefix` this command shows connected prefixes to advertise. + +.. opcmd:: show ipv6 ospfv3 route + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. + +.. opcmd:: show ipv6 ospfv3 border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. + +.. opcmd:: show ipv6 ospfv3 database + + This command displays a summary table with a database contents (LSA). + +.. opcmd:: show ipv6 ospfv3 database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link + advertisement type. + +.. opcmd:: show ipv6 ospfv3 redistribute + + This command displays external information redistributed into OSPFv3 + + +Configuration Example +--------------------- + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 redistribute connected + +**Node 2:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 + set protocols ospfv3 parameters router-id 192.168.2.1 + set protocols ospfv3 redistribute connected + +**To see the redistributed routes:** + +.. code-block:: none + + show ipv6 ospfv3 redistribute + +.. note:: You cannot easily redistribute IPv6 routes via OSPFv3 on a + WireGuard interface link. This requires you to configure link-local + addresses manually on the WireGuard interfaces, see :vytask:`T1483`. + +Example configuration for WireGuard interfaces: + +**Node 1** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' + set interfaces wireguard wg01 address '192.168.0.1/24' + set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' + set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Node 2** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' + set interfaces wireguard wg01 address '192.168.0.2/24' + set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' + set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.2 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Status** + +.. code-block:: none + + vyos@ospf01:~$ sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + + vyos@ospf02# run sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] + diff --git a/docs/configuration/protocols/pim.disable b/docs/configuration/protocols/pim.disable new file mode 100644 index 00000000..1dd373d8 --- /dev/null +++ b/docs/configuration/protocols/pim.disable @@ -0,0 +1,2 @@ +PIM +###
\ No newline at end of file diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst new file mode 100644 index 00000000..4d46e2f0 --- /dev/null +++ b/docs/configuration/protocols/rip.rst @@ -0,0 +1,255 @@ +.. _rip: + +### +RIP +### + +:abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + + - RIPv1 as described in :rfc:`1058` + - RIPv2 as described in :rfc:`2453` + +General Configuration +--------------------- + +.. cfgcmd:: set protocols rip network <A.B.C.D/M> + + This command enables RIP and sets the RIP enable interface by NETWORK. + The interfaces which have addresses matching with NETWORK are enabled. + +.. cfgcmd:: set protocols rip interface <interface> + + This command specifies a RIP enabled interface by interface name. Both + the sending and receiving of RIP packets will be enabled on the port + specified in this command. + +.. cfgcmd:: set protocols rip neighbor <A.B.C.D> + + This command specifies a RIP neighbor. When a neighbor doesn’t understand + multicast, this command is used to specify neighbors. In some cases, not + all routers will be able to understand multicasting, where packets are + sent to a network or a group of addresses. In a situation where a neighbor + cannot process multicast packets, it is necessary to establish a direct + link between routers. + +.. cfgcmd:: set protocols rip passive-interface interface <interface> + + This command sets the specified interface to passive mode. On passive mode + interface, all receiving packets are processed as normal and VyOS does not + send either multicast or unicast RIP packets except to RIP neighbors + specified with neighbor command. + +.. cfgcmd:: set protocols rip passive-interface interface default + + This command specifies all interfaces to passive mode. + + +Optional Configuration +---------------------- + +.. cfgcmd:: set protocols rip default-distance <distance> + + This command change distance value of RIP. The distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> distance <distance> + + This command sets default RIP distance to specified value when the route’s + source IP address matches the specified prefix. + +.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> access-list <name> + + This command can be used with previous command to sets default RIP distance + to specified value when the route’s source IP address matches the specified + prefix and the specified access-list. + +.. cfgcmd:: set protocols rip default-information originate + + This command generate a default route into the RIP. + +.. cfgcmd:: set protocols rip distribute-list access-list <in|out> <number> + + This command can be used to filter the RIP path using access lists. + :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the access + lists are applied. + +.. cfgcmd:: set protocols rip distribute-list interface <interface> access-list <in|out> <number> + + This command allows you apply access lists to a chosen interface to + filter the RIP path. + +.. cfgcmd:: set protocols rip distribute-list prefix-list <in|out> <name> + + This command can be used to filter the RIP path using prefix lists. + :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the prefix + lists are applied. + +.. cfgcmd:: set protocols rip distribute-list interface <interface> prefix-list <in|out> <name> + + This command allows you apply prefix lists to a chosen interface to + filter the RIP path. + +.. cfgcmd:: set protocols rip route <A.B.C.D/M> + + This command is specific to FRR and VyOS. The route command makes a static + route only inside RIP. This command should be used only by advanced users + who are particularly knowledgeable about the RIP protocol. In most cases, + we recommend creating a static route in VyOS and redistributing it in RIP + using :cfgcmd:`redistribute static`. + +.. cfgcmd:: set protocols rip timers update <seconds> + + This command specifies the update timer. Every update timer seconds, the + RIP process is awakened to send an unsolicited response message containing + the complete routing table to all neighboring RIP routers. The time range + is 5 to 2147483647. The default value is 30 seconds. + +.. cfgcmd:: set protocols rip timers timeout <seconds> + + This command specifies the timeout timer. Upon expiration of the timeout, + the route is no longer valid; however, it is retained in the routing table + for a short time so that neighbors can be notified that the route has been + dropped. The time range is 5 to 2147483647. The default value is 180 + seconds. + +.. cfgcmd:: set protocols rip timers garbage-collection <seconds> + + This command specifies the garbage-collection timer. Upon expiration of + the garbage-collection timer, the route is finally removed from the + routing table. The time range is 5 to 2147483647. The default value is 120 + seconds. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols rip redistribute <route source> + + This command redistributes routing information from the given route source + into the RIP tables. There are five modes available for route source: bgp, + connected, kernel, ospf, static. + +.. cfgcmd:: set protocols rip redistribute <route source> metric <metric> + + This command specifies metric for redistributed routes from the given route + source. There are five modes available for route source: bgp, connected, + kernel, ospf, static. The metric range is 1 to 16. + +.. cfgcmd:: set protocols rip redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are five modes available for route source: + bgp, connected, kernel, ospf, static. + +.. cfgcmd:: set protocols rip default-metric <metric> + + This command modifies the default metric (hop count) value for redistributed + routes. The metric range is 1 to 16. The default value is 1. This command + does not affect connected route even if it is redistributed by + :cfgcmd:`redistribute connected`. To modify connected route’s metric + value, please use :cfgcmd:`redistribute connected metric`. + + +Interfaces Configuration +------------------------ + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication plaintext-password <text> + + This command sets the interface with RIP simple password authentication. + This command also sets authentication string. The string must be shorter + than 16 characters. + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication md5 <id> password <text> + + This command sets the interface with RIP MD5 authentication. This command + also sets MD5 Key. The key must be shorter than 16 characters. + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon disable + + This command disables split-horizon on the interface. By default, VyOS does + not advertise RIP routes out the interface over which they were learned + (split horizon). + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon poison-reverse + + This command enables poison-reverse on the interface. If both poison reverse + and split horizon are enabled, then VyOS advertises the learned routes + as unreachable over the interface on which the route was learned. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ip rip + + This command displays RIP routes. + +.. code-block:: none + + Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP + Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time + C(i) 10.0.12.0/24 0.0.0.0 1 self 0 + C(i) 10.0.13.0/24 0.0.0.0 1 self 0 + R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 + +.. opcmd:: show ip rip status + + The command displays current RIP status. It includes RIP timer, filtering, + version, RIP enabled interface and RIP peer information. + +.. code-block:: none + + Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) + + +Configuration Example +--------------------- + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces loopback address 10.1.1.1/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +**Node 2:** + +.. code-block:: none + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected diff --git a/docs/configuration/protocols/ripng.disable b/docs/configuration/protocols/ripng.disable new file mode 100644 index 00000000..dec6bddf --- /dev/null +++ b/docs/configuration/protocols/ripng.disable @@ -0,0 +1,3 @@ +##### +RIPng +#####
\ No newline at end of file diff --git a/docs/routing/rpki.rst b/docs/configuration/protocols/rpki.rst index 9813b1b6..d9884296 100644 --- a/docs/routing/rpki.rst +++ b/docs/configuration/protocols/rpki.rst @@ -34,6 +34,10 @@ in :rfc:`8210`. tools). It also has some `help and operational guidance`_ including "What can I do about my route having an Invalid state?" +*************** +Getting started +*************** + First you will need to deploy an RPKI validator for your routers to use. The RIPE NCC helpfully provide `some instructions`_ to get you started with several different options. Once your server is running you can start @@ -71,14 +75,95 @@ Imported prefixes during the validation may have values: reading about Krill_ if this is a rabbit hole you need or especially want to dive down. +Features of the Current Implementation +====================================== + +In a nutshell, the current implementation provides the following features: + +* The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. + +* If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. + +* By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. + +* Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. + +* Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +************* +Configuration +************* + +.. cfgcmd:: protocols rpki polling-period <1-86400> + + Define the time interval to update the local cache + + The default value is 300 seconds. + +.. cfgcmd:: protocols rpki cache <address> port <port> + + Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching + instance which is used. + + This is a mandatory setting. + +.. cfgcmd:: protocols rpki cache <address> preference <preference> + + Multiple RPKI caching instances can be supplied and they need a preference in + which their result sets are used. + + This is a mandatory setting. + +SSH +=== + +Connections to the RPKI caching server can not only be established by HTTP/TLS +but you can also rely on a secure SSH session to the server. To enable SSH you +first need to create yoursels an SSH client keypair using ``generate ssh +client-key /config/auth/id_rsa_rpki``. Once your key is created you can setup +the connection. + +.. cfgcmd:: protocols rpki cache <address> ssh username <user> + + SSH username to establish an SSH connection to the cache server. + +.. cfgcmd:: protocols rpki cache <address> ssh known-hosts-file <filepath> + + Local path that includes the known hosts file. + +.. cfgcmd:: protocols rpki cache <address> ssh private-key-file <filepath> + + Local path that includes the private key file of the router. + +.. cfgcmd:: protocols rpki cache <address> ssh public-key-file <filepath + + Local path that includes the public key file of the router. + +.. note:: When using SSH, known-hosts-file, private-key-file and public-key-file + are mandatory options. + +******* +Example +******* + We can build route-maps for import based on these states. Here is a simple RPKI configuration, where `routinator` is the RPKI-validating "cache" server with ip `192.0.2.1`: .. code-block:: none - set protocols rpki cache routinator address '192.0.2.1' - set protocols rpki cache routinator port '3323' + set protocols rpki cache 192.0.2.1 port '3323' + set protocols rpki cache 192.0.2.1 preference '1' Here is an example route-map to apply to routes learned at import. In this filter we reject prefixes with the state `invalid`, and set a higher @@ -100,6 +185,8 @@ Once your routers are configured to reject RPKI-invalid prefixes, you can test whether the configuration is working correctly using the `RIPE Labs RPKI Test`_ experimental tool. +.. stop_vyoslinter + .. _tweet by EvilMog: https://twitter.com/Evil_Mog/status/1230924170508169216 .. _Routinator: https://www.nlnetlabs.nl/projects/rpki/routinator/ .. _GoRTR: https://github.com/cloudflare/gortr @@ -110,4 +197,6 @@ Test`_ experimental tool. .. _RPKI analytics: https://www.nlnetlabs.nl/projects/rpki/rpki-analytics/ .. _RIPE Labs RPKI Test: https://sg-pub.ripe.net/jasper/rpki-web-test/ .. _excellent guide to RPKI: https://rpki.readthedocs.io/ -.. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.html +.. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.htm + +.. start_vyoslinter diff --git a/docs/routing/static.rst b/docs/configuration/protocols/static.rst index 523627fa..723db727 100644 --- a/docs/routing/static.rst +++ b/docs/configuration/protocols/static.rst @@ -15,8 +15,9 @@ collection of all routes the router has learned from its configuration or from its dynamic routing protocols is stored in the RIB. Unicast routes are directly used to determine the forwarding table used for unicast packet forwarding. +************* Static Routes -############# +************* .. cfgcmd:: set protocols static route <subnet> next-hop <address> @@ -27,7 +28,8 @@ Static Routes Disable this IPv4 static route entry. -.. cfgcmd:: set protocols static route <subnet> next-hop <address> distance <distance> +.. cfgcmd:: set protocols static route <subnet> next-hop <address> + distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -46,7 +48,8 @@ Static Routes Disable this IPv6 static route entry. -.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> distance <distance> +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> + distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -60,34 +63,40 @@ Static Routes Interface Routes ================ -.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> +.. cfgcmd:: set protocols static route <subnet> interface + <interface> Allows you to configure the next-hop interface for an interface-based IPv4 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> disable +.. cfgcmd:: set protocols static route <subnet> interface + <interface> disable Disables interface-based IPv4 static route. -.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> distance <distance> +.. cfgcmd:: set protocols static route <subnet> interface + <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. Range is 1 to 255, default is 1. -.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> Allows you to configure the next-hop interface for an interface-based IPv6 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> disable +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> disable Disables interface-based IPv6 static route. -.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> distance <distance> +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -132,3 +141,68 @@ TBD Alternate routing tables are used with policy based routing of by utilizing :ref:`vrf`. + + +.. _routing-arp: + +### +ARP +### + +:abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for +discovering the link layer address, such as a MAC address, associated with a +given internet layer address, typically an IPv4 address. This mapping is a +critical function in the Internet protocol suite. ARP was defined in 1982 by +:rfc:`826` which is Internet Standard STD 37. + +In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is +provided by the Neighbor Discovery Protocol (NDP). + +To manipulate or display ARP_ table entries, the following commands are +implemented. + +********* +Configure +********* + +.. cfgcmd:: set protocols static arp <address> hwaddr <mac> + + This will configure a static ARP entry always resolving `<address>` to + `<mac>`. + + Example: + + .. code-block:: none + + set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + + +********* +Operation +********* + + +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + + +.. opcmd:: show protocols static arp interface eth1 + + Display all known ARP table entries on a given interface only (`eth1`): + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + +.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/protocols/vrf.disable b/docs/configuration/protocols/vrf.disable new file mode 100644 index 00000000..e7609a77 --- /dev/null +++ b/docs/configuration/protocols/vrf.disable @@ -0,0 +1,3 @@ +############# +Protocols VRF +############# diff --git a/docs/services/udp-broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index df48bfd6..df48bfd6 100644 --- a/docs/services/udp-broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst diff --git a/docs/services/conntrack.rst b/docs/configuration/service/conntrack-sync.rst index 90f062e8..3c9f08e4 100644 --- a/docs/services/conntrack.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt Conntrack --------- @@ -26,6 +26,12 @@ tunnels it can be their tunnel ID, but otherwise is just zero, as if it were not part of the tuple. To be able to inspect the TCP port in all cases, packets will be mandatorily defragmented. +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + Configuration ^^^^^^^^^^^^^ @@ -51,9 +57,12 @@ Configuration # Interface to use for syncing conntrack entries [REQUIRED] set service conntrack-sync interface <ifname> - + # Multicast group to use for syncing conntrack entries set service conntrack-sync mcast-group <x.x.x.x> + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface <ifname> peer <remote IP of peer> # Queue size for syncing conntrack entries (in MB) set service conntrack-sync sync-queue-size <size> @@ -110,7 +119,8 @@ Now configure conntrack-sync service on ``router1`` **and** ``router2`` set service conntrack-sync mcast-group '225.0.0.50' set service conntrack-sync sync-queue-size '8' -If you are using VRRP, you need to define a VRRP sync-group, and use ``vrrp sync-group`` instead of ``cluster group``. +If you are using VRRP, you need to define a VRRP sync-group, and use +``vrrp sync-group`` instead of ``cluster group``. .. code-block:: none diff --git a/docs/services/console-server.rst b/docs/configuration/service/console-server.rst index c9b48114..a509723e 100644 --- a/docs/services/console-server.rst +++ b/docs/configuration/service/console-server.rst @@ -44,7 +44,8 @@ second. This is also the default setting if none of those options are defined. Configure either one or two stop bits. This defaults to one stop bits if left unconfigured. -.. cfgcmd:: set service console-server <device> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] +.. cfgcmd:: set service console-server <device> speed + [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] .. note:: USB to serial converters will handle most of their work in software so you should be carefull with the selected baudrate as some times they @@ -82,7 +83,7 @@ Operation Show currently connected users. - .. code-block:: + .. code-block:: none vyos@vyos:~$ show console-server user usb0b2.4p1.0 up vyos@localhost diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..5355a0fd --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,159 @@ +.. _dhcp-relay: + +########## +DHCP Relay +########## + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. + +********** +IPv4 relay +********** + +Configuration +============= + +.. cfgcmd:: set service dhcp-relay interface <interface> + + Enable the DHCP relay service on the given interface. + +.. cfgcmd:: set service dhcp-relay server <server> + + Configure IP address of the DHCP `<server>` which will handle the relayed + packets. + +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets discard + + The router should discard DHCP packages already containing relay agent + information to ensure that only requests from DHCP clients are forwarded. + +Options +------- + +.. cfgcmd:: set service dhcp-relay relay-options hop-count <count> + + Set the maximum hop `<count>` before packets are discarded. Range 0...255, + default 10. + +.. cfgcmd:: set service dhcp-relay relay-options max-size <size> + + Set maximum `<size>` of DHCP packets including relay agent information. If a + DHCP packet size surpasses this value it will be forwarded without appending + relay agent information. Range 64...1400, default 576. + +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet + <append | discard | forward | replace> + + Four policies for reforwarding DHCP packets exist: + + * **append:** The relay agent is allowed to append its own relay information + to a received DHCP packet, disregarding relay information already present + in the packet. + + * **discard:** Received packets which already contain relay information will + be discarded. + + * **forward:** All packets are forwarded, relay information already present + will be ignored. + + * **replace:** Relay information already present in a packet is stripped and + replaced with the router's own relay information set. + +Example +======= + +* Listen for DHCP requests on interface ``eth1``. +* DHCP server is located at IPv4 address 10.0.1.4. +* Router receives DHCP client requests on ``eth1`` and relays them to the server + at 10.0.1.4. + +.. figure:: /_static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +The generated configuration will look like: + +.. code-block:: none + + show service dhcp-relay + interface eth1 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + +Operation +========= + +.. opcmd:: restart dhcp relay-agent + + Restart DHCP relay service + +********** +IPv6 relay +********** + +Configuration +============= + +.. cfgcmd:: set service dhcpv6-relay listen-interface <interface> + + Set eth1 to be the listening interface for the DHCPv6 relay. + + Multiple interfaces may be specified. + +.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> + address <server> + + Specifies an upstream network `<interface>` from which replies from + `<server>` and other relay agents will be accepted. + +Options +------- + +.. cfgcmd:: set service dhcpv6-relay max-hop-count 'count' + + Set maximum hop count before packets are discarded, default: 10 + +.. cfgcmd:: set service dhcpv6-relay use-interface-id-option + + If this is set the relay agent will insert the interface ID. This option is + set automatically if more than one listening interfaces are in use. + +Example +======= + +* DHCPv6 requests are received by the router on `listening interface` ``eth1`` +* Requests are forwarded through ``eth2`` as the `upstream interface` +* External DHCPv6 server is at 2001:db8::4 + +.. figure:: /_static/images/service_dhcpv6-relay01.png + :scale: 80 % + :alt: DHCPv6 relay example + + DHCPv6 relay example + +The generated configuration will look like: + +.. code-block:: none + + commit + show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } + +Operation +========= + +.. opcmd:: restart dhcpv6 relay-agent + + Restart DHCPv6 relay agent immediately. diff --git a/docs/services/dhcp.rst b/docs/configuration/service/dhcp-server.rst index 8655d177..28dddb2f 100644 --- a/docs/services/dhcp.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -1,15 +1,14 @@ -.. _dhcp: - -############# -DHCP / DHCPv6 -############# - -VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. - .. _dhcp-server: +########### DHCP Server -=========== +########### + +VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. + +*********** +IPv4 server +*********** The network topology is declared by shared-network-name and the subnet declarations. The DHCP service can serve multiple shared networks, with each @@ -20,7 +19,7 @@ mappings can be set to assign "static" addresses to clients based on their MAC address. Configuration -------------- +============= .. cfgcmd:: set service dhcp-server shared-network-name <name> authoritative @@ -29,76 +28,88 @@ Configuration any device trying to request an IP address that is not valid for this network. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> default-router <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + default-router <address> This is a configuration parameter for the `<subnet>`, saying that as part of the response, tell the client that the default gateway can be reached at `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> dns-server <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + dns-server <address> This is a configuration parameter for the subnet, saying that as part of the response, tell the client that the DNS server can be found at `<address>`. Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> lease <time> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + lease <time> Assign the IP address to this machine for `<time>` seconds. The default value is 86400 seconds which corresponds to one day. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> range <n> start <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> start <address> Create DHCP address range with a range id of `<n>`. DHCP leases are taken from this pool. The pool starts at address `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> range <n> stop <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> stop <address> Create DHCP address range with a range id of `<n>`. DHCP leases are taken from this pool. The pool stops with address `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> exclude <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + exclude <address> Always exclude this address from any defined range. This address will never be assigned by the DHCP server. This option can be specified multiple times. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> domain-name <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP Option 015). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> domain-search <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-search <domain-name> The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). - Failover -^^^^^^^^ +-------- VyOS provides support for DHCP failover. DHCP failover must be configured explicitly by the following statements. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover local-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover local-address <address> Local IP `<address>` used when communicating to the failover peer. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover peer-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover peer-address <address> - Remote peer IP `<address>` of the second DHCP server in this failover cluster. + Remote peer IP `<address>` of the second DHCP server in this failover + cluster. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover name <name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover name <name> A generic `<name>` referencing this sync service. .. note:: `<name>` must be identical on both sides! -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover status <primary | secondary> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover status <primary | secondary> The primary and secondary statements determines whether the server is primary or secondary. @@ -109,26 +120,27 @@ explicitly by the following statements. .. hint:: The dialogue between failover partners is neither encrypted nor authenticated. Since most DHCP servers exist within an organisation's own - secure Intranet, this would be an unnecessary overhead. However, if you have - DHCP failover peers whose communications traverse insecure networks, then we - recommend that you consider the use of VPN tunneling between them to ensure - that the failover partnership is immune to disruption (accidental or - otherwise) via third parties. - + secure Intranet, this would be an unnecessary overhead. However, if you + have DHCP failover peers whose communications traverse insecure networks, + then we recommend that you consider the use of VPN tunneling between them + to ensure that the failover partnership is immune to disruption + (accidental or otherwise) via third parties. Static mappings -^^^^^^^^^^^^^^^ +--------------- You can specify a static DHCP assignment on a per host basis. You will need the MAC address of the station and your desired IP address. The address must be inside the subnet definition but can be outside of the range statement. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> mac-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> mac-address <address> Create a new DHCP static mapping named `<description>` which is valid for the host identified by its MAC `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> ip-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> ip-address <address> Static DHCP IP address assign to host identified by `<description>`. IP address must be inside the `<subnet>` which is defined but can be outside @@ -138,11 +150,11 @@ inside the subnet definition but can be outside of the range statement. This is useful, for example, in combination with hostfile update. - .. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. - + .. hint:: This is the equivalent of the host block in dhcpd.conf of + isc-dhcpd. Options -^^^^^^^ +======= .. list-table:: :header-rows: 1 @@ -157,12 +169,14 @@ Options * - client-prefix-length - 1 - subnet-mask - - Specifies the clients subnet mask as per RFC 950. If unset, subnet declaration is used. + - Specifies the clients subnet mask as per RFC 950. If unset, + subnet declaration is used. - N * - time-offset - 2 - time-offset - - Offset of the client's subnet in seconds from Coordinated Universal Time (UTC) + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) - N * - default-router - 3 @@ -272,9 +286,8 @@ Options Multi: can be specified multiple times. - Raw Parameters -^^^^^^^^^^^^^^ +============== Raw parameters can be passed to shared-network-name, subnet and static-mapping: @@ -299,44 +312,15 @@ Quotes can be used inside parameter values by replacing all quote characters with the string ``"``. They will be replaced with literal quote characters when generating dhcpd.conf. - Example -^^^^^^^ - -Quick-Start -""""""""""" - -* We are offering address space in the `192.0.2.0/24` network. -* We are using the network name `mypool`. - -.. code-block:: none - - set service dhcp-server shared-network-name mypool authoritative - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 default-router 192.0.2.1 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 dns-server 192.0.2.1 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 lease 86400 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 start 192.0.2.100 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 stop 192.0.2.199 - -The generated config will look like: - -.. code-block:: none - - vyos@vyos# show service dhcp-server shared-network-name mypool - authoritative - subnet 192.0.2.0/24 { - default-router 192.0.2.1 - dns-server 192.0.2.1 - lease 86400 - range 0 { - start 192.0.2.100 - stop 192.0.2.199 - } - } +======= +Please see the :ref:`dhcp-dns-quick-start` configuration. Failover -"""""""" +-------- + +Configuration of a DHCP failover pair * Setup DHCP failover for network 192.0.2.0/24 * Default gateway and DNS server is at `192.0.2.254` @@ -344,37 +328,38 @@ Failover * The secondary DHCP server uses address `192.168.189.253` * DHCP range spans from `192.168.189.10` - `192.168.189.250` -**Primary** +Common configuration, valid for both primary and secondary node. .. code-block:: none set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' + + +**Primary** + +.. code-block:: none + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.252' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.253' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250' **Secondary** .. code-block:: none - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.253' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.252' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250' Raw Parameters -"""""""""""""" +-------------- * Override static-mapping's dns-server with a custom one that will be sent only to this host. @@ -390,9 +375,8 @@ Raw Parameters set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" - Operation Mode --------------- +============== .. opcmd:: restart dhcp server @@ -422,8 +406,8 @@ Operation Mode vyos@vyos:~$ show dhcp server leases IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- - 192.0.2.104 aa:bb:cc:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 - 192.0.2.115 ab:ac:ad:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + 192.0.2.104 00:53:01:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 + 192.0.2.115 00:53:01:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 .. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. @@ -442,66 +426,76 @@ Operation Mode Show only leases with the specified state. Possible states: all, active, free, expired, released, abandoned, reset, backup (default = active) -DHCPv6 Server -============= +*********** +IPv6 server +*********** VyOS also provides DHCPv6 server functionality which is described in this section. -Configuration Options ---------------------- +Configuration +============= .. cfgcmd:: set service dhcpv6-server preference <preference value> Clients receiving advertise messages from multiple servers choose the server with the highest preference value. The range for this value is ``0...255``. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> lease-time {default | maximum | minimum} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> lease-time {default | maximum | minimum} The default lease time for DHCPv6 leases is 24 hours. This can be changed by supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All values need to be supplied in seconds. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-domain <domain-name> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-domain <domain-name> A :abbr:`NIS (Network Information Service)` domain can be set to be used for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-domain <domain-name> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-domain <domain-name> The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` domain is similar to the NIS domain one: -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-server <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-server <address> Specify a NIS server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-server <address> Specify a NIS+ server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server <address | fqdn> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sip-server <address | fqdn> Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address of Fully Qualified Domain Name for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sntp-server-address <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sntp-server-address <address> A SNTP server address can be specified for DHCPv6 clients. Prefix Delegation -^^^^^^^^^^^^^^^^^ +----------------- To hand out individual prefixes to your clients the following configuration is used: -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> prefix-length <length> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> prefix-length <length> Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when they request for prefix delegation. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> stop <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> stop <address> Delegate prefixes from the range indicated by the start and stop qualifier. @@ -541,7 +535,7 @@ The configuration will look as follows: } Static mappings -^^^^^^^^^^^^^^^ +--------------- In order to map specific IPv6 addresses to specific hosts static mappings can be created. The following example explains the process. @@ -564,6 +558,8 @@ be created. The following example explains the process. The configuration will look as follows: +.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) + .. code-block:: none show service dhcp-server shared-network-name NET1 @@ -582,8 +578,10 @@ The configuration will look as follows: } } +.. start_vyoslinter + Operation Mode --------------- +============== .. opcmd:: restart dhcpv6 server @@ -621,158 +619,3 @@ Operation Mode Show only leases with the specified state. Possible states: abandoned, active, all, backup, expired, free, released, reset (default = active) - -DHCP Relay -========== - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. See -https://wiki.vyos.net/wiki/Network_address_setup. - - -Configuration -------------- - -.. cfgcmd:: set service dhcp-relay interface <interface> - - Enable the DHCP relay service on the given interface. - -.. cfgcmd:: set service dhcp-relay server <server> - - Configure IP address of the DHCP `<server>` which will handle the relayed - packets. - -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets discard - - The router should discard DHCP packages already containing relay agent - information to ensure that only requests from DHCP clients are forwarded. - -Example -------- - -* Listen for DHCP requests on interface ``eth1``. -* DHCP server is located at IPv4 address 10.0.1.4. -* Router receives DHCP client requests on ``eth1`` and relays them to the server at 10.0.1.4. - -.. figure:: /_static/images/service_dhcp-relay01.png - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -The generated configuration will look like: - -.. code-block:: none - - show service dhcp-relay - interface eth1 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -Options -------- - -.. cfgcmd:: set service dhcp-relay relay-options hop-count <count> - - Set the maximum hop `<count>` before packets are discarded. Range 0...255, - default 10. - -.. cfgcmd:: set service dhcp-relay relay-options max-size <size> - - Set maximum `<size>` of DHCP packets including relay agent information. If a - DHCP packet size surpasses this value it will be forwarded without appending - relay agent information. Range 64...1400, default 576. - -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet <append | discard | forward | replace> - - Four policies for reforwarding DHCP packets exist: - - * **append:** The relay agent is allowed to append its own relay information - to a received DHCP packet, disregarding relay information already present in - the packet. - - * **discard:** Received packets which already contain relay information will - be discarded. - - * **forward:** All packets are forwarded, relay information already present - will be ignored. - - * **replace:** Relay information already present in a packet is stripped and - replaced with the router's own relay information set. - -Operation ---------- - -.. opcmd:: restart dhcp relay-agent - - Restart DHCP relay service - -DHCPv6 relay -============ - -Configuration -------------- - -.. cfgcmd:: set service dhcpv6-relay listen-interface <interface> - - Set eth1 to be the listening interface for the DHCPv6 relay. - - Multiple interfaces may be specified. - -.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> address <server> - - Specifies an upstream network `<interface>` from which replies from `<server>` - and other relay agents will be accepted. - -Example -^^^^^^^ - -* DHCPv6 requests are received by the router on `listening interface` ``eth1`` -* Requests are forwarded through ``eth2`` as the `upstream interface` -* External DHCPv6 server is at 2001:db8::4 - -.. figure:: /_static/images/service_dhcpv6-relay01.png - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -The generated configuration will look like: - -.. code-block:: none - - commit - show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8::4 - } - -Options -------- - -.. cfgcmd:: set service dhcpv6-relay max-hop-count 'count' - - Set maximum hop count before packets are discarded, default: 10 - -.. cfgcmd:: set service dhcpv6-relay use-interface-id-option - - If this is set the relay agent will insert the interface ID. This option is - set automatically if more than one listening interfaces are in use. - -Operation ---------- - -.. opcmd:: show dhcpv6 relay-agent status - - Show the current status of the DHCPv6 relay agent: - -.. opcmd:: restart dhcpv6 relay-agent - - Restart DHCPv6 relay agent immediately. diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst new file mode 100644 index 00000000..0a65161b --- /dev/null +++ b/docs/configuration/service/dns.rst @@ -0,0 +1,328 @@ +.. _dns-forwarding: + +############## +DNS Forwarding +############## + +Configuration +============= + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +.. cfgcmd:: set service dns forwarding system + + Forward incoming DNS queries to the DNS servers configured under the ``system + name-server`` nodes. + +.. cfgcmd:: set service dns forwarding name-server <address> + + Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. + You can configure multiple nameservers here. + +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> + + Forward received queries for a particular domain + (specified via `domain-name`) to a given nameserver. Multiple nameservers + can be specified. You can use this feature for a DNS split-horizon + configuration. + + .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). + +.. cfgcmd:: set service dns forwarding allow-from <network> + + Given the fact that open DNS recursors could be used on DDoS amplification + attacks, you must configure the networks which are allowed to use this + recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and + IPv6 networks to query this server. This is generally a bad idea. + +.. cfgcmd:: set service dns forwarding dnssec + <off | process-no-validate | process | log-fail | validate> + + The PowerDNS recursor has 5 different levels of DNSSEC processing, which can + be set with the dnssec setting. In order from least to most processing, these + are: + + * **off** In this mode, no DNSSEC processing takes place. The recursor will + not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the + DO and AD bits in queries. + + * **process-no-validate** In this mode the recursor acts as a "security + aware, non-validating" nameserver, meaning it will set the DO-bit on + outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to + clients that ask for them (by means of a DO-bit in the query), except for + zones provided through the auth-zones setting. It will not do any + validation in this mode, not even when requested by the client. + + * **process** When dnssec is set to process the behavior is similar to + process-no-validate. However, the recursor will try to validate the data + if at least one of the DO or AD bits is set in the query; in that case, + it will set the AD-bit in the response when the data is validated + successfully, or send SERVFAIL when the validation comes up bogus. + + * **log-fail** In this mode, the recursor will attempt to validate all data + it retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before + turning on full-blown validation. Responses to client queries are the same + as with process. + + * **validate** The highest mode of DNSSEC processing. In this mode, all + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. + + .. note:: The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. + This might lead to unexpected query results when testing. Set ``+noad`` + on the ``dig`` command line when this is the case. + + .. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + + Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP + server will use this file to add resolvers to assigned addresses. + +.. cfgcmd:: set service dns forwarding max-cache-entries + + Maximum number of DNS cache entries. 1 million per CPU core will generally + suffice for most installations. + +.. cfgcmd:: set service dns forwarding negative-ttl + + A query for which there is authoritatively no answer is cached to quickly + deny a record's existence later on, without putting a heavy load on the + remote server. In practice, caches can become saturated with hundreds of + thousands of hosts which are tried only once. This setting, which defaults + to 3600 seconds, puts a maximum on the amount of time negative entries are + cached. + +.. cfgcmd:: set service dns forwarding listen-address + + The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder + will listen on this address for incoming connections. + +Example +======= + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + +In this scenario: + +* All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +* All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +* The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com server 2001:db8:cafe::1 + set service dns forwarding name-server 192.0.2.1 + set service dns forwarding name-server 192.0.2.2 + set service dns forwarding name-server 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + set service dns forwarding listen-address 192.168.1.254 + set service dns forwarding listen-address 2001:db8::ffff + set service dns forwarding allow-from 192.168.1.0/24 + set service dns forwarding allow-from 2001:db8::/64 + +Operation +========= + +.. opcmd:: reset dns forwarding <all | domain> + + Resets the local DNS forwarding cache database. You can reset the cache + for all entries or only for entries to a specific domain. + +.. opcmd:: restart dns forwarding + + Restarts the DNS recursor process. This also invalidates the local DNS + forwarding cache. + + +.. _dynamic-dns: + +########### +Dynamic DNS +########### + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes ddclient_, a Perl script written for +this only one purpose. + +ddclient_ uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second +one involves a third party service, like DynDNS.com or any other similar +website. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +Configuration +============= + +:rfc:`2136` Based +----------------- + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + + Create new :rfc:`2136` DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + key <keyfile> + + File identified by `<keyfile>` containing the secret RNDC key shared with + remote DNS server. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + server <server> + + Configure the DNS `<server>` IP/FQDN used when updating this dynamic + assignment. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + zone <zone> + + Configure DNS `<zone>` to be updated. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + record <record> + + Configure DNS `<record>` which should be updated. This can be set multiple + times. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + ttl <ttl> + + Configure optional TTL value on the given resource record. This defaults to + 600 seconds. + +Example +^^^^^^^ + +* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` +* Use auth key file at ``/config/auth/my.key`` +* Set TTL to 300 seconds + +.. code-block:: none + + vyos@vyos# show service dns dynamic + interface eth0.7 { + rfc2136 VyOS-DNS { + key /config/auth/my.key + record example.vyos.io + server ns1.vyos.io + ttl 300 + zone vyos.io + } + } + +This will render the following ddclient_ configuration entry: + +.. code-block:: none + + # + # ddclient configuration for interface "eth0.7": + # + use=if, if=eth0.7 + + # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io + server=ns1.vyos.io + protocol=nsupdate + password=/config/auth/my.key + ttl=300 + zone=vyos.io + example.vyos.io + +.. note:: You can also keep different DNS zone updated. Just create a new + config node: ``set service dns dynamic interface <interface> rfc2136 + <other-service-name>`` + +HTTP based services +------------------- + +VyOS is also able to use any service relying on protocols supported by ddclient. + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + host-name <hostname> + + Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS + provider identified by `<service>` when the IP address on interface + `<interface>` changes. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + login <username> + + Configure `<username>` used when authenticating the update request for + DynDNS service identified by `<service>`. + For Namecheap, set the <domain> you wish to update. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + password <password> + + Configure `<password>` used when authenticating the update request for + DynDNS service identified by `<service>`. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + protocol <protocol> + + When a ``custom`` DynDNS provider is used the protocol used for communicating + to the provider must be specified under `<protocol>`. See the embedded + completion helper for available protocols. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + server <server> + + When a ``custom`` DynDNS provider is used the `<server>` where update + requests are being sent to must be specified. + +Example: +^^^^^^^^ + +Use DynDNS as your preferred provider: + +.. code-block:: none + + set service dns dynamic interface eth0 service dyndns + set service dns dynamic interface eth0 service dyndns login my-login + set service dns dynamic interface eth0 service dyndns password my-password + set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + +.. note:: Multiple services can be used per interface. Just specify as many + services per interface as you like! + +Running Behind NAT +------------------ + +By default, ddclient_ will update a dynamic dns record using the IP address +directly attached to the interface. If your VyOS instance is behind NAT, your +record will be updated to point to your internal IP. + +ddclient_ has another way to determine the WAN IP address. This is controlled +by: + +.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> + + Use configured `<url>` to determine your IP address. ddclient_ will load + `<url>` and tries to extract your IP address from the response. + +.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> + + ddclient_ will skip any address located before the string set in `<pattern>`. + +.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/appendix/http-api.rst b/docs/configuration/service/https.rst index 49f2dbd9..b9c691da 100644 --- a/docs/appendix/http-api.rst +++ b/docs/configuration/service/https.rst @@ -39,23 +39,34 @@ leave appropriate defaults in the nginx directive. Multiple instances of Configuration mode requests --------------------------- -In our example, we are creating a dummy interface and assigning an address to it: +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. +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: +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. +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. +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: @@ -91,9 +102,11 @@ Passing an empty path will return the full config: Configuration management requests --------------------------------- -When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. +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: +If you don't specify the file when saving, it saves to ``/config/config.boot``. +Here's an example: .. code-block:: none @@ -102,7 +115,8 @@ If you don't specify the file when saving, it saves to ``/config/config.boot``. Image management requests ------------------------- -One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: +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: @@ -116,7 +130,8 @@ One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here # 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: +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 diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst new file mode 100644 index 00000000..fb194239 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,25 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + console-server + dhcp-relay + dhcp-server + dns + https + ipoe-server + lldp + mdns + pppoe-server + router-advert + snmp + ssh + tftp-server + webproxy diff --git a/docs/services/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 96c96527..7858ff19 100644 --- a/docs/services/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _ipoe_server: @@ -41,8 +41,8 @@ the configuration. set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' @@ -119,13 +119,13 @@ example configuration can be used. set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' Bandwidth Shaping -^^^^^^^^^^^^^^^^^ +================= Bandwidth rate limits can be set for local users within the configuration or via RADIUS based attributes. Bandwidth Shaping for local users -================================= +--------------------------------- The rate-limit is set in kbit/sec. @@ -134,8 +134,8 @@ The rate-limit is set in kbit/sec. set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' .. code-block:: none @@ -146,4 +146,4 @@ The rate-limit is set in kbit/sec. -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/services/lldp.rst b/docs/configuration/service/lldp.rst index 4b1743e6..aa357211 100644 --- a/docs/services/lldp.rst +++ b/docs/configuration/service/lldp.rst @@ -12,7 +12,8 @@ as Station and Media Access Control Connectivity Discovery specified in IEEE 802.1AB and IEEE 802.3-2012 section 6 clause 79. LLDP performs functions similar to several proprietary protocols, such as -:abbr:`CDP (Cisco Discovery Protocol)`, :abbr:`FDP (Foundry Discovery Protocol)`, +:abbr:`CDP (Cisco Discovery Protocol)`, +:abbr:`FDP (Foundry Discovery Protocol)`, :abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology Discovery)`. diff --git a/docs/services/mdns-repeater.rst b/docs/configuration/service/mdns.rst index 9d6a292a..9d6a292a 100644 --- a/docs/services/mdns-repeater.rst +++ b/docs/configuration/service/mdns.rst diff --git a/docs/configuration/service/pppoe-advert.disable b/docs/configuration/service/pppoe-advert.disable new file mode 100644 index 00000000..bbb82202 --- /dev/null +++ b/docs/configuration/service/pppoe-advert.disable @@ -0,0 +1,2 @@ +pppoe-advert +############
\ No newline at end of file diff --git a/docs/services/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index e710ba6a..8d895f9d 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -29,7 +29,8 @@ First steps Use this command to define whether your PPPoE clients will locally authenticate in your VyOS system or in RADIUS server. -.. cfgcmd:: set service pppoe-server authentication local-users username <name> password <password> +.. cfgcmd:: set service pppoe-server authentication local-users username + <name> password <password> Use this command to configure the username and the password of a locally configured user. @@ -39,7 +40,7 @@ First steps Use this command to define the interface the PPPoE server will use to listen for PPPoE clients. -.. cfgcmd:: set service pppoe-server local-ip <address> +.. cfgcmd:: set service pppoe-server gateway-address <address> Use this command to configure the local gateway IP address. @@ -57,7 +58,7 @@ To automatically assign the client an IP address as tunnel endpoint, a client IP pool is needed. The source can be either RADIUS or a local subnet or IP range definition. -Once the local tunnel endpoint ``set service pppoe-server local-ip +Once the local tunnel endpoint ``set service pppoe-server gateway-address '10.1.1.2'`` has been defined, the client IP pool can be either defined as a range or as subnet using CIDR notation. If the CIDR notation is used, multiple subnets can be setup which are used sequentially. @@ -103,7 +104,8 @@ used, multiple subnets can be setup which are used sequentially. To use a radius server, you need to switch to authentication mode RADIUS and then configure it. -.. cfgcmd:: set service pppoe-server authentication radius server <address> key <secret> +.. cfgcmd:: set service pppoe-server authentication radius server <address> + key <secret> Use this command to configure the IP address and the shared secret key of your RADIUS server. You can have multiple RADIUS servers @@ -116,14 +118,15 @@ and then configure it. set service pppoe-server authentication mode 'radius' set service pppoe-server authentication radius server 10.1.100.1 key 'secret' set service pppoe-server interface 'eth1' - set service pppoe-server local-ip '10.1.1.2' + set service pppoe-server gateway-address '10.1.1.2' RADIUS provides the IP addresses in the example above via Framed-IP-Address. **RADIUS sessions management DM/CoA** -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author <key | port | server> +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author + <key | port | server> Use this command to configure Dynamic Authorization Extensions to RADIUS so that you can remotely disconnect sessions and change some @@ -141,7 +144,8 @@ username test .. code-block:: none - root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 disconnect secret123 + root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 + disconnect secret123 You can also use another attributes for identify client for disconnect, like Framed-IP-Address, Acct-Session-Id, etc. Result commands appears in @@ -155,7 +159,8 @@ Example for changing rate-limit via RADIUS CoA. .. code-block:: none - echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa secret123 + echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa + secret123 Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit up-stream rate) If attribute Filter-Id redefined, replace it in RADIUS @@ -164,7 +169,8 @@ CoA request. Automatic VLAN Creation ----------------------- -.. cfgcmd:: set service pppoe-server interface <interface> <vlan-id | vlan range> <text> +.. cfgcmd:: set service pppoe-server interface <interface> + <vlan-id | vlan range> <text> VLAN's can be created by accel-ppp on the fly via the use of a Kernel module named `vlan_mon`, which is monitoring incoming vlans and @@ -193,7 +199,8 @@ attributes. For Local Users ^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server authentication local-users username <name> rate-limit <download | upload> +.. cfgcmd:: set service pppoe-server authentication local-users username <name> + rate-limit <download | upload> Use this command to configure a data-rate limit to PPPOoE clients for traffic download or upload. The rate-limit is set in kbit/sec. @@ -210,7 +217,7 @@ For Local Users set service pppoe-server name-server '10.100.100.1' set service pppoe-server name-server '10.100.200.1' set service pppoe-server interface 'eth1' - set service pppoe-server local-ip '10.1.1.2' + set service pppoe-server gateway-address '10.1.1.2' Once the user is connected, the user session is using the set limits and @@ -248,7 +255,8 @@ Load Balancing -------------- -.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> sessions <number-of-sessions> +.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> + sessions <number-of-sessions> Use this command to enable the delay of PADO (PPPoE Active Discovery Offer) packets, which can be used as a session balancing mechanism @@ -273,7 +281,8 @@ IPv6 IPv6 client's prefix assignment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> mask <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> + mask <number-of-bits> Use this comand to set the IPv6 address pool from which a PPPoE client will get an IPv6 prefix of your defined length (mask) to @@ -284,7 +293,8 @@ IPv6 client's prefix assignment IPv6 Prefix Delegation ^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> + delegation-prefix <number-of-bits> Use this command to configure DHCPv6 Prefix Delegation (RFC3633). You will have to set your IPv6 pool and the length of the delegation @@ -359,7 +369,7 @@ address from the pool 10.1.1.100-111, terminates at the local endpoint set service pppoe-server client-ip-pool start '10.1.1.100' set service pppoe-server client-ip-pool stop '10.1.1.111' set service pppoe-server interface eth1 - set service pppoe-server local-ip '10.1.1.2' + set service pppoe-server gateway-address '10.1.1.2' set service pppoe-server name-server '10.100.100.1' set service pppoe-server name-server '10.100.200.1' @@ -378,10 +388,10 @@ The example below covers a dual-stack configuration via pppoe-server. set service pppoe-server client-ip-pool stop '192.168.0.10' set service pppoe-server client-ipv6-pool delegate '2001:db8:8003::/48' delegation-prefix '56' set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::/48' mask '64' - set service pppoe-server name-server '8.8.8.8' - set service pppoe-server name-server '2001:4860:4860::8888' + set service pppoe-server name-server '10.1.1.1' + set service pppoe-server name-server '2001:db8:4860::8888' set service pppoe-server interface 'eth2' - set service pppoe-server local-ip '10.100.100.1' + set service pppoe-server gateway-address '10.100.100.1' The client, once successfully authenticated, will receive an IPv4 and an IPv6 /64 address to terminate the pppoe endpoint on the client side and @@ -394,4 +404,4 @@ a /56 subnet for the clients internal use. --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/services/router-advert.rst b/docs/configuration/service/router-advert.rst index bc92f315..36fa600d 100644 --- a/docs/services/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -29,6 +29,8 @@ Enabling Advertisments .. cfgcmd:: set service router-advert interface <interface> .... +.. stop_vyoslinter + .. csv-table:: :header: "Field", "VyOS Option", "Description" :widths: 10, 10, 20 @@ -45,11 +47,16 @@ Enabling Advertisments "DNSSL", "dnssl", "DNS search list to advertise" "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" +.. start_vyoslinter + + Advertising a Prefix '''''''''''''''''''' .. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 +.. stop_vyoslinter + .. csv-table:: :header: "VyOS Field", "Description" :widths: 10,30 @@ -59,6 +66,7 @@ Advertising a Prefix "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" +.. start_vyoslinter Disabling Advertisements ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,10 +86,10 @@ Example Configuration interval { max 600 } - name-server 2001:4860:4860::8888 - name-server 2001:4860:4860::8844 + name-server 2001:db8::1 + name-server 2001:db8::2 other-config-flag - prefix 2001:DB8:beef:2::/64 { + prefix 2001:db8:beef:2::/64 { valid-lifetime 2592000 } reachable-time 0 diff --git a/docs/configuration/service/salt-minion.disable b/docs/configuration/service/salt-minion.disable new file mode 100644 index 00000000..63df57a4 --- /dev/null +++ b/docs/configuration/service/salt-minion.disable @@ -0,0 +1,2 @@ +salt-minion +###########
\ No newline at end of file diff --git a/docs/services/snmp.rst b/docs/configuration/service/snmp.rst index 3f445ea8..e962c1c5 100644 --- a/docs/services/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -223,10 +223,13 @@ Once the script is uploaded, it needs to be configured via the command below. set service snmp script-extensions extension-name my-extension script your_script.sh commit +.. stop_vyoslinter The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will contain the output of the extension. +.. start_vyoslinter + .. code-block:: none root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 @@ -241,9 +244,12 @@ SolarWinds If you happen to use SolarWinds Orion as NMS you can also use the Device Templates Management. A template for VyOS can be easily imported. +.. stop_vyoslinter + Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the following content: + .. code-block:: none <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> @@ -264,3 +270,4 @@ following content: .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 .. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst new file mode 100644 index 00000000..94249766 --- /dev/null +++ b/docs/configuration/service/ssh.rst @@ -0,0 +1,157 @@ +.. _ssh: + +### +SSH +### + +:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due + to tighter security in VyOS 1.2. + +.. seealso:: SSH :ref:`ssh_key_based_authentication` + +Configuration +============= + +.. cfgcmd:: set service ssh port <port> + + Enabling SSH only requires you to specify the port ``<port>`` you want SSH to + listen on. By default, SSH runs on port 22. + +.. cfgcmd:: set service ssh listen-address <address> + + Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be + defined. + +.. cfgcmd:: set service ssh ciphers <cipher> + + Define allowed ciphers used for the SSH connection. A number of allowed + ciphers can be specified, use multiple occurrences to allow multiple ciphers. + + List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, + ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, + ``arcfour128``, ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` + +.. cfgcmd:: set service ssh disable-password-authentication + + Disable password based authentication. Login via SSH keys only. This hardens + security! + +.. cfgcmd:: set service ssh disable-host-validation + + Disable the host validation through reverse DNS lookups - can speedup login + time when reverse lookup is not possible. + +.. cfgcmd:: set service ssh macs <mac> + + Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. + The MAC algorithm is used in protocol version 2 for data integrity protection. + Multiple algorithms can be provided. + + List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, + ``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, + ``umac-64@openssh.com``, ``umac-128@openssh.com``, + ``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``, + ``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``, + ``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``, + ``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``, + ``umac-128-etm@openssh.com`` + +.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> + + Add access-control directive to allow or deny users and groups. Directives + are processed in the following order of precedence: ``deny-users``, + ``allow-users``, ``deny-groups`` and ``allow-groups``. + +.. cfgcmd:: set service ssh client-keepalive-interval <interval> + + Specify timeout interval for keepalive message in seconds. + +.. cfgcmd:: set service ssh key-exchange <kex> + + Specify allowed :abbr:`KEX (Key Exchange)` algorithms. + + List of supported algorithms: ``diffie-hellman-group1-sha1``, + ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, + ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, + ``diffie-hellman-group-exchange-sha1``, + ``diffie-hellman-group-exchange-sha256``, + ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, + ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. + +.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> + + Set the ``sshd`` log level. The default is ``info``. + +.. cfgcmd:: set service ssh vrf <name> + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. + +Operation +========= + +.. opcmd:: restart ssh + + Restart the SSH daemon process, the current session is not affected, only the + background daemon is restarted. + +.. opcmd:: generate ssh server-key + + Re-generated the public/private keyportion which SSH uses to secure + connections. + + .. note:: Already learned known_hosts files of clients need an update as the + public key will change. + +.. opcmd:: generate ssh client-key /path/to/private_key + + Re-generated a known pub/private keyfile which can e.g. used to connect to + other services (RPKI cache). + + Example: + + .. code-block:: none + + vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki + Generating public/private rsa key pair. + Your identification has been saved in /config/auth/id_rsa_rpki. + Your public key has been saved in /config/auth/id_rsa_rpki.pub. + The key fingerprint is: + SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q cpo@LR1.wue3 + The key's randomart image is: + +---[RSA 2048]----+ + | oo | + | ..o | + | . o.o.. o.| + | o+ooo o.o| + | Eo* =.o | + | o = +.o*+ | + | = o *.o.o| + | o * +.o+.+| + | =.. o=.oo| + +----[SHA256]-----+ + + Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub`` + will be created. diff --git a/docs/services/tftp.rst b/docs/configuration/service/tftp-server.rst index 276ce5fb..276ce5fb 100644 --- a/docs/services/tftp.rst +++ b/docs/configuration/service/tftp-server.rst diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst new file mode 100644 index 00000000..e8f6423e --- /dev/null +++ b/docs/configuration/service/webproxy.rst @@ -0,0 +1,434 @@ +.. _webproxy: + +######## +Webproxy +######## + +The proxy service in VyOS is based on Squid_ and some related modules. + +Squid_ is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by SquidGuard_. + +************* +Configuration +************* + +.. cfgcmd:: set service webproxy append-domain <domain> + + Use this command to specify a domain name to be appended to domain-names + within URLs that do not include a dot ``.`` the domain is appended. + + Example: to be appended is set to ``vyos.net`` and the URL received is + ``www/foo.html``, the system will use the generated, final URL of + ``www.vyos.net/foo.html``. + + .. code-block:: none + + set service webproxy append-domain vyos.net + +.. cfgcmd:: set service webproxy cache-size <size> + + The size of the on-disk Proxy cache is user configurable. The Proxies default + cache-size is configured to 100 MB. + + Unit of this command is MB. + + .. code-block:: none + + set service webproxy cache-size 1024 + +.. cfgcmd:: set service webproxy default-port <port> + + Specify the port used on which the proxy service is listening for requests. + This port is the default port used for the specified listen-address. + + Default port is 3128. + + .. code-block:: none + + set service webproxy default-port 8080 + +.. cfgcmd:: set service webproxy domain-block <domain> + + Used to block specific domains by the Proxy. Specifying "vyos.net" will block + all access to vyos.net, and specifying ".xxx" will block all access to URLs + having an URL ending on .xxx. + + .. code-block:: none + + set service webproxy domain-block vyos.net + +.. cfgcmd:: set service webproxy domain-noncache <domain> + + Allow access to sites in a domain without retrieving them from the Proxy + cache. Specifying "vyos.net" will allow access to vyos.net but the pages + accessed will not be cached. It useful for working around problems with + "If-Modified-Since" checking at certain sites. + + .. code-block:: none + + set service webproxy domain-noncache vyos.net + +.. cfgcmd:: set service webproxy listen-address <address> + + Specifies proxy service listening address. The listen address is the IP + address on which the web proxy service listens for client requests. + + For security, the listen address should only be used on internal/trusted + networks! + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 + +.. cfgcmd:: set service webproxy listen-address <address> disable-transparent + + Disables web proxy transparent mode at a listening address. + + In transparent proxy mode, all traffic arriving on port 80 and destined for + the Internet is automatically forwarded through the proxy. This allows + immediate proxy forwarding without configuring client browsers. + + Non-transparent proxying requires that the client browsers be configured with + the proxy settings before requests are redirected. The advantage of this is + that the client web browser can detect that a proxy is in use and can behave + accordingly. In addition, web-transmitted malware can sometimes be blocked by + a non-transparent web proxy, since they are not aware of the proxy settings. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 disable-transparent + +.. cfgcmd:: set service webproxy listen-address <address> port <port> + + Sets the listening port for a listening address. This overrides the default + port of 3128 on the specific listen address. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 port 8080 + + +.. cfgcmd:: set service webproxy reply-block-mime <mime> + + Used to block a specific mime-type. + + .. code-block:: none + + # block all PDFs + set service webproxy reply-block-mime application/pdf + + +.. cfgcmd:: set service webproxy reply-body-max-size <size> + + Specifies the maximum size of a reply body in KB, used to limit the reply + size. + + All reply sizes are accepted by default. + + .. code-block:: none + + set service webproxy reply-body-max-size 2048 + +Authentication +============== + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +.. cfgcmd:: set service webproxy authentication children <number> + + Maximum number of authenticator processes to spawn. If you start too few + Squid will have to wait for them to process a backlog of credential + verifications, slowing it down. When password verifications are done via a + (slow) network you are likely to need lots of authenticator processes. + + This defaults to 5. + + .. code-block:: none + + set service webproxy authentication children 10 + +.. cfgcmd:: set service webproxy authentication credentials-ttl <time> + + Specifies how long squid assumes an externally validated username:password + pair is valid for - in other words how often the helper program is called for + that user. Set this low to force revalidation with short lived passwords. + + Time is in minutes and defaults to 60. + + .. code-block:: none + + set service webproxy authentication credentials-ttl 120 + + +.. cfgcmd:: set service webproxy authentication method <ldap> + + Proxy authentication method, currently only LDAP is supported. + + .. code-block:: none + + set service webproxy authentication method ldap + +.. cfgcmd:: set service webproxy authentication realm + + Specifies the protection scope (aka realm name) which is to be reported to + the client for the authentication scheme. It is commonly part of the text + the user will see when prompted for their username and password. + + .. code-block:: none + + set service webproxy authentication realm "VyOS proxy auth" + +LDAP +---- + +.. cfgcmd:: set service webproxy authentication ldap base-dn <base-dn> + + Specifies the base DN under which the users are located. + + .. code-block:: none + + set service webproxy authentication ldap base-dn DC=vyos,DC=net + + +.. cfgcmd:: set service webproxy authentication ldap bind-dn <bind-dn> + + The DN and password to bind as while performing searches. + + .. code-block:: none + + set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net + +.. cfgcmd:: set service webproxy authentication ldap filter-expression <expr> + + LDAP search filter to locate the user DN. Required if the users are in a + hierarchy below the base DN, or if the login name is not what builds the user + specific part of the users DN. + + The search filter can contain up to 15 occurrences of %s which will be + replaced by the username, as in "uid=%s" for :rfc:`2037` directories. For a + detailed description of LDAP search filter syntax see :rfc:`2254`. + + .. code-block:: none + + set service webproxy authentication ldap filter-expression (cn=%s) + +.. cfgcmd:: set service webproxy authentication ldap password <password> + + The DN and password to bind as while performing searches. As the password + needs to be printed in plain text in your Squid configuration it is strongly + recommended to use a account with minimal associated privileges. This to limit + the damage in case someone could get hold of a copy of your Squid + configuration file. + + .. code-block:: none + + set service webproxy authentication ldap password vyos + +.. cfgcmd:: set service webproxy authentication ldap persistent-connection + + Use a persistent LDAP connection. Normally the LDAP connection is only open + while validating a username to preserve resources at the LDAP server. This + option causes the LDAP connection to be kept open, allowing it to be reused + for further user validations. + + Recommended for larger installations. + + .. code-block:: none + + set service webproxy authentication ldap persistent-connection + +.. cfgcmd:: set service webproxy authentication ldap port <port> + + Specify an alternate TCP port where the ldap server is listening if other than + the default LDAP port 389. + + .. code-block:: none + + set service webproxy authentication ldap port 389 + +.. cfgcmd:: set service webproxy authentication ldap server <server> + + Specify the LDAP server to connect to. + + .. code-block:: none + + set service webproxy authentication ldap server ldap.vyos.net + + +.. cfgcmd:: set service webproxy authentication ldap use-ssl + + Use TLS encryption. + + .. code-block:: none + + set service webproxy authentication ldap use-ssl + + +.. cfgcmd:: set service webproxy authentication ldap username-attribute <attr> + + Specifies the name of the DN attribute that contains the username/login. + Combined with the base DN to construct the users DN when no search filter is + specified (`filter-expression`). + + Defaults to 'uid' + + .. note:: This can only be done if all your users are located directly under + the same position in the LDAP tree and the login name is used for naming + each user object. If your LDAP tree does not match these criterias or if you + want to filter who are valid users then you need to use a search filter to + search for your users DN (`filter-expression`). + + .. code-block:: none + + set service webproxy authentication ldap username-attribute uid + +.. cfgcmd:: set service webproxy authentication ldap version <2 | 3> + + LDAP protocol version. Defaults to 3 if not specified. + + .. code-block:: none + + set service webproxy authentication ldap version 2 + +URL filtering +============= + +.. include:: /_include/need_improvement.txt + + +.. cfgcmd:: set service webproxy url-filtering disable + + Disables web filtering without discarding configuration. + + .. code-block:: none + + set service webproxy url-filtering disable + +********* +Operation +********* + +.. include:: /_include/need_improvement.txt + +Filtering +========= + +Update +------ + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + + +.. opcmd:: update webproxy blacklists + + Download/Update complete blacklist + + .. code-block:: none + + vyos@vyos:~$ update webproxy blacklists + Warning: No url-filtering blacklist installed + Would you like to download a default blacklist? [confirm][y] + Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) + blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA + Uncompressing blacklist... + Checking permissions... + Skip link for [ads] -> [publicite] + Building DB for [adult/domains] - 2467177 entries + Building DB for [adult/urls] - 67798 entries + Skip link for [aggressive] -> [agressif] + Building DB for [agressif/domains] - 348 entries + Building DB for [agressif/urls] - 36 entries + Building DB for [arjel/domains] - 69 entries + ... + + Building DB for [webmail/domains] - 374 entries + Building DB for [webmail/urls] - 9 entries + + The webproxy daemon must be restarted + Would you like to restart it now? [confirm][y] + + [ ok ] Restarting squid (via systemctl): squid.service. + vyos@vyos:~$ + +.. opcmd:: update webproxy blacklists category <category> + + Download/Update partial blacklist. + + Use tab completion to get a list of categories. + +* To auto update the blacklist files + + :code:`set service webproxy url-filtering squidguard auto-update + update-hour 23` + +* To configure blocking add the following to the configuration + + :code:`set service webproxy url-filtering squidguard block-category ads` + + :code:`set service webproxy url-filtering squidguard block-category malware` + +Bypassing the webproxy +---------------------- + +.. include:: /_include/need_improvement.txt + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +* To bypass the proxy for every request that is directed to a specific + destination: + + :code:`set service webproxy whitelist destination-address 198.51.100.33` + + :code:`set service webproxy whitelist destination-address 192.0.2.0/24` + + +* To bypass the proxy for every request that is coming from a specific source: + + :code:`set service webproxy whitelist source-address 192.168.1.2` + + :code:`set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +******** +Examples +******** + +.. code-block:: none + + vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } + +.. _Squid: http://www.squid-cache.org/ +.. _SquidGuard: http://www.squidguard.org/ diff --git a/docs/configuration/system/acceleration.disable b/docs/configuration/system/acceleration.disable new file mode 100644 index 00000000..b09da38b --- /dev/null +++ b/docs/configuration/system/acceleration.disable @@ -0,0 +1,7 @@ +.. _acceleration: + +############ +Acceleration +############ + + diff --git a/docs/configuration/system/config-management.disable b/docs/configuration/system/config-management.disable new file mode 100644 index 00000000..40973713 --- /dev/null +++ b/docs/configuration/system/config-management.disable @@ -0,0 +1,2 @@ +config-management +#################
\ No newline at end of file diff --git a/docs/configuration/system/conntrack.disable b/docs/configuration/system/conntrack.disable new file mode 100644 index 00000000..7d5d4308 --- /dev/null +++ b/docs/configuration/system/conntrack.disable @@ -0,0 +1,2 @@ +conntrack +#########
\ No newline at end of file diff --git a/docs/system/serial-console.rst b/docs/configuration/system/console.rst index 4a750ada..4890da92 100644 --- a/docs/system/serial-console.rst +++ b/docs/configuration/system/console.rst @@ -38,6 +38,9 @@ Major upgrades to the installed distribution may also require console access. * ``57600`` - 57,600 bps * ``115200`` - 115,200 bps (default for serial console) - .. note:: If you use a USB to serial converter please note that most of them - use software emulation without flow control, thus you should start with a - common baud rate of 9600 as otherwise you could get + .. note:: If you use USB to serial converters for connecting to your VyOS + appliance please note that most of them use software emulation without flow + control. This means you should start with a common baud rate (most likely + 9600 baud) as otherwise you probably can not connect to the device using + high speed baud rates as your serial converter simply can not process this + datarate. diff --git a/docs/system/default-route.rst b/docs/configuration/system/default-route.rst index 27c74188..27c74188 100644 --- a/docs/system/default-route.rst +++ b/docs/configuration/system/default-route.rst diff --git a/docs/configuration/system/domain-name.disable b/docs/configuration/system/domain-name.disable new file mode 100644 index 00000000..9028b65b --- /dev/null +++ b/docs/configuration/system/domain-name.disable @@ -0,0 +1,2 @@ +domain-name +###########
\ No newline at end of file diff --git a/docs/configuration/system/domain-search.disable b/docs/configuration/system/domain-search.disable new file mode 100644 index 00000000..f4aef62e --- /dev/null +++ b/docs/configuration/system/domain-search.disable @@ -0,0 +1,2 @@ +domain-search +#############
\ No newline at end of file diff --git a/docs/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst index a68b3924..3eab4e2c 100644 --- a/docs/system/eventhandler.rst +++ b/docs/configuration/system/eventhandler.rst @@ -3,9 +3,11 @@ Event Handler ------------- -Event handler allows you to execute scripts when a string that matches a regex appears in a text stream (e.g. log file). +Event handler allows you to execute scripts when a string that matches a regex +appears in a text stream (e.g. log file). -It uses "feeds" (output of commands, or a named pipes) and "policies" that define what to execute if a regex is matched. +It uses "feeds" (output of commands, or a named pipes) and "policies" that +define what to execute if a regex is matched. .. code-block:: none @@ -27,7 +29,8 @@ It uses "feeds" (output of commands, or a named pipes) and "policies" that defin pattern <regex> run <command to run> -In this small example a script runs every time a login failed and an interface goes down +In this small example a script runs every time a login failed and an interface +goes down .. code-block:: none diff --git a/docs/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index f09c1c9a..8d46b178 100644 --- a/docs/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -54,7 +54,7 @@ interface, the interface must be configured for flow accounting. accounting. .. note:: Will be recorded only packets/flows on **incoming** direction in - configured interfaces. + configured interfaces by default. By default, recorded flows will be saved internally and can be listed with the @@ -62,6 +62,11 @@ CLI command. You may disable using the local in-memory table with the command: .. cfgcmd:: set system flow-accounting disable-imt + If you need to sample also egress traffic, you may want to + configure egress flow-accounting: + +.. cfgcmd:: set system flow-accounting enable-egress + Internally, in flow-accounting processes exist a buffer for data exchanging between core process and plugins (each export target is a separated plugin). If you have high traffic levels or noted some problems with missed records @@ -121,7 +126,8 @@ NetFlow Per default every packet is sampled (that is, the sampling rate is 1). -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval <interval> +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + <interval> Specifies the interval at which Netflow data will be sent to a collector. As per default, Netflow data will be sent every 60 seconds. diff --git a/docs/system/host-information.rst b/docs/configuration/system/host-name.rst index 30efe01e..30efe01e 100644 --- a/docs/system/host-information.rst +++ b/docs/configuration/system/host-name.rst diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst new file mode 100644 index 00000000..2e428333 --- /dev/null +++ b/docs/configuration/system/index.rst @@ -0,0 +1,31 @@ +###### +System +###### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + console + flow-accounting + host-name + ip + ipv6 + lcd + login + name-server + ntp + option + proxy + syslog + task-scheduler + time-zone + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + default-route + eventhandler diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..78aeef4e --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,70 @@ +## +IP +## + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + +.. cfgcmd:: set system ip arp table-size <number> + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: none + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: none + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route
\ No newline at end of file diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst new file mode 100644 index 00000000..cba5c0e0 --- /dev/null +++ b/docs/configuration/system/ipv6.rst @@ -0,0 +1,182 @@ +#### +IPv6 +#### + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable + + Use this command to disable assignment of IPv6 addresses on all + interfaces. + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + +.. cfgcmd:: set system ipv6 neighbor table-size <number> + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list + +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show BGP information for given address or prefix + <X:X::X:X/M> + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status + + +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset ipv6 bgp <address> + + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors <address | interface> + + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route.
\ No newline at end of file diff --git a/docs/system/lcd.rst b/docs/configuration/system/lcd.rst index 441becf5..808d45a2 100644 --- a/docs/system/lcd.rst +++ b/docs/configuration/system/lcd.rst @@ -41,5 +41,5 @@ Configuration .. note:: We can't support all displays from the beginning. If your display type is missing, please create a feature request via Phabricator_. -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/system/user-management.rst b/docs/configuration/system/login.rst index d3dcc378..0492f4d1 100644 --- a/docs/system/user-management.rst +++ b/docs/configuration/system/login.rst @@ -19,13 +19,15 @@ Local Create new system user with username `<name>` and real-name specified by `<string>`. -.. cfgcmd:: set system login user <name> authentication plaintext-password <password> +.. cfgcmd:: set system login user <name> authentication plaintext-password + <password> Specify the plaintext password user by user `<name>` on this system. The plaintext password will be automatically transferred into a secure hashed password and not saved anywhere in plaintext. -.. cfgcmd:: set system login user <name> authentication encrypted-password <password> +.. cfgcmd:: set system login user <name> authentication encrypted-password + <password> Setup encrypted password for given username. This is useful for transferring a hashed password from system to system. @@ -50,12 +52,14 @@ and paste it. Some terminal emulators may accidentally split this over several lines. Be attentive when you paste it that it only pastes as a single line. The third part is simply an identifier, and is for your own reference. -.. cfgcmd:: set system login user <username> authentication public-keys <identifier> key <key> +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> key <key> Assign the SSH public key portion `<key>` identified by per-key `<identifier>` to the local user `<username>`. -.. cfgcmd:: set system login user <username> authentication public-keys <identifier> type <type> +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> type <type> Every SSH public key portion referenced by `<identifier>` requires the configuration of the `<type>` of public-key used. This type can be any of: @@ -78,7 +82,7 @@ The third part is simply an identifier, and is for your own reference. using one of the following :abbr:`URIs (Uniform Resource Identifier)`: * ``<file>`` - Load from file on local filesystem path - * ``scp://<user>@<host>/<file>`` - Load via SCP from remote machine + * ``scp://<user>@<host>:/<file>`` - Load via SCP from remote machine * ``sftp://<user>@<host>/<file>`` - Load via SFTP from remote machine * ``ftp://<user>@<host>/<file>`` - Load via FTP from remote machine * ``http://<host>/<file>`` - Load via HTTP from remote machine diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst new file mode 100644 index 00000000..1896eeda --- /dev/null +++ b/docs/configuration/system/name-server.rst @@ -0,0 +1,71 @@ +.. _system-dns: + +########## +System DNS +########## + + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server <address> + + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +.. stop_vyoslinter + +.. code-block:: none + + set system name-server 176.9.37.132 + set system name-server 195.10.195.195 + set system name-server 2a01:4f8:161:3441::1 + set system name-server 2a00:f826:8:2::195 + +.. start_vyoslinter + +Domain search order +=================== + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + + +.. cfgcmd:: set system domain-search domain <domain> + + Use this command to define domains, one at a time, so that the system + uses them to complete unqualified host names. Maximum: 6 entries. + + +.. note:: Domain names can include letters, numbers, hyphens and periods + with a maximum length of 253 characters. + + +Example +------- + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + + +.. code-block:: none + + set system domain-search domain vyos.io + set system domain-search domain vyos.net + set system domain-search domain vyos.network + diff --git a/docs/configuration/system/name-servers-dhcp.disable b/docs/configuration/system/name-servers-dhcp.disable new file mode 100644 index 00000000..6719fef9 --- /dev/null +++ b/docs/configuration/system/name-servers-dhcp.disable @@ -0,0 +1,2 @@ +name-servers-dhcp +#################
\ No newline at end of file diff --git a/docs/system/ntp.rst b/docs/configuration/system/ntp.rst index 5fd1837f..223447f5 100644 --- a/docs/system/ntp.rst +++ b/docs/configuration/system/ntp.rst @@ -40,17 +40,38 @@ Configuration There are 3 default NTP server set. You are able to change them. - * 0.pool.ntp.org - * 1.pool.ntp.org - * 2.pool.ntp.org + * ``0.pool.ntp.org`` + * ``1.pool.ntp.org`` + * ``2.pool.ntp.org`` + +.. cfgcmd:: set system ntp server <address> <noselect | pool | preempt | prefer> + + Configure one or more attributes to the given NTP server. + + * ``noselect`` marks the server as unused, except for display purposes. The + server is discarded by the selection algorithm. + + * ``pool`` mobilizes persistent client mode association with a number of + remote servers. + + * ``preempt`` a preemptable association is expendable. + + * ``prefer`` marks the server as preferred. All other things being equal, + this host will be chosen for synchronization among a set of correctly + operating hosts. .. cfgcmd:: set system ntp listen-address <address> - Setup VyOS as an NTP responder, you must specify the `<address>` and - optionally the permitted clients. Multiple listen addresses can be - configured. + NTP process will only listen on the specified IP address. You must specify + the `<address>` and optionally the permitted clients. Multiple listen + addresses can be configured. .. cfgcmd:: set system ntp allow-clients address <address> List of networks or client addresses permitted to contact this NTP server. + Multiple networks can be configured. + +.. cfgcmd:: set system ntp vrf <name> + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst new file mode 100644 index 00000000..e029ec96 --- /dev/null +++ b/docs/configuration/system/option.rst @@ -0,0 +1,100 @@ +.. _system_option: + +###### +Option +###### + +This chapter describe the possibilities of advanced system behavior. + +******* +General +******* + +.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff> + + Action which will be run once the ctrl-alt-del keystroke is received. + +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. + +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. + +*********** +HTTP client +*********** + +.. cfgcmd:: set system option http-client source-address <address> + + Several commands utilize curl to initiate transfers. Configure the local + source IPv4/IPv6 address used for all CURL operations. + +.. cfgcmd:: set system option http-client source-interface <interface> + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. + +.. note:: `source-address` and `source-interface` can not be used at the same + time. + +*************** +Keyboard Layout +*************** + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +.. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH oder Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. + +.. _system_options_performance: + +*********** +Performance +*********** + +As more and more routers run on Hypervisors, expecially with a :abbr:`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + +.. stop_vyoslinter + +.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf + +.. start_vyoslinter + +.. cfgcmd:: set system option performance < throughput | latency > + + Configure one of the predefined system performance profiles. + + * ``throughput``: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, + ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to + 40%. + + * ``latency``: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``min_perf_pct=100``. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. diff --git a/docs/system/proxy.rst b/docs/configuration/system/proxy.rst index 8e0339a7..8e0339a7 100644 --- a/docs/system/proxy.rst +++ b/docs/configuration/system/proxy.rst diff --git a/docs/configuration/system/static-host-mapping.disable b/docs/configuration/system/static-host-mapping.disable new file mode 100644 index 00000000..97d9a443 --- /dev/null +++ b/docs/configuration/system/static-host-mapping.disable @@ -0,0 +1,2 @@ +static-host-mapping +###################
\ No newline at end of file diff --git a/docs/configuration/system/sysctl.disable b/docs/configuration/system/sysctl.disable new file mode 100644 index 00000000..82ffd159 --- /dev/null +++ b/docs/configuration/system/sysctl.disable @@ -0,0 +1,2 @@ +sysctl +######
\ No newline at end of file diff --git a/docs/system/syslog.rst b/docs/configuration/system/syslog.rst index 3a8b344a..a4d641b5 100644 --- a/docs/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -22,9 +22,9 @@ Console .. cfgcmd:: set system syslog console facility <keyword> level <keyword> -Log syslog messages to ``/dev/console``, for en explanation on -:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords -see tables below. + Log syslog messages to ``/dev/console``, for an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. Custom File @@ -32,20 +32,21 @@ Custom File .. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> -Log syslog messages to file specified via `<filename>`, for en explanation on -:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see -tables below. + Log syslog messages to file specified via `<filename>`, for en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. .. cfgcmd:: set system syslog file <filename> archive size <size> -Syslog will write `<size>` kilobytes into the file specified by `<filename>`. -After this limit has been reached, the custom file is "rotated" by logrotate -and a new custom file is created. + Syslog will write `<size>` kilobytes into the file specified by `<filename>`. + After this limit has been reached, the custom file is "rotated" by logrotate + and a new custom file is created. .. cfgcmd:: set system syslog file <filename> archive file <number> -Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep -as many as `<number>` rotated file before they are deleted on the system. + Syslog uses logrotate to rotate logiles after a number of gives bytes. + We keep as many as `<number>` rotated file before they are deleted on the + system. Remote Host @@ -59,16 +60,17 @@ sending the messages via port 514/UDP. .. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> -Log syslog messages to remote host specified by `<address>`. The address can be -specified by either FQDN or IP address. For en explanation on -:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see -tables below. + Log syslog messages to remote host specified by `<address>`. The address + can be specified by either FQDN or IP address. For en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` + keywords see tables below. -.. cfgcmd:: set system syslog host <address> facility <keyword> protocol <udp|tcp> +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol + <udp|tcp> -Configure protocol used for communication to remote syslog host. This can be -either UDP or TCP. + Configure protocol used for communication to remote syslog host. This can be + either UDP or TCP. Local User Account @@ -76,11 +78,11 @@ Local User Account .. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword> -If logging to a local user account is configured, all defined log messages are -display on the console if the local user is logged in, if the user is not -logged in, no messages are being displayed. For en explanation on -:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see -tables below. + If logging to a local user account is configured, all defined log messages + are display on the console if the local user is logged in, if the user is not + logged in, no messages are being displayed. For en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. .. _syslog_facilities: @@ -191,36 +193,39 @@ Display Logs .. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] -Display log files of given category on the console. Use tab completion to get -a list of available categories. Thos categories could be: all, authorization, -cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image -lldp, nat, openvpn, snmp, tail, vpn, vrrp + Display log files of given category on the console. Use tab completion to get + a list of available categories. Thos categories could be: all, authorization, + cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image + lldp, nat, openvpn, snmp, tail, vpn, vrrp If no option is specified, this defaults to `all`. -.. opcmd:: show log image <name> [all | authorization | directory | file <file name> | tail <lines>] - -Log messages from a specified image can be displayed on the console. Details of -allowed parameters: - -.. list-table:: - :widths: 25 75 - :header-rows: 0 - - * - all - - Display contents of all master log files of the specified image - * - authorization - - Display all authorization attempts of the specified image - * - directory - - Display list of all user-defined log files of the specified image - * - file <file name> - - Display contents of a specified user-defined log file of the specified image - * - tail - - Display last lines of the system log of the specified image - * - <lines> - - Number of lines to be displayed, default 10 +.. opcmd:: show log image <name> + [all | authorization | directory | file <file name> | tail <lines>] + + Log messages from a specified image can be displayed on the console. Details + of allowed parameters: + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file <file name> + - Display contents of a specified user-defined log file of the specified + image + * - tail + - Display last lines of the system log of the specified image + * - <lines> + - Number of lines to be displayed, default 10 When no options/parameters are used, the contents of the main syslog file are displayed. -.. hint:: Use ``show log | strip-private`` if you want to hide private data when sharing your logs. +.. hint:: Use ``show log | strip-private`` if you want to hide private data + when sharing your logs. diff --git a/docs/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst index 382da39f..382da39f 100644 --- a/docs/system/task-scheduler.rst +++ b/docs/configuration/system/task-scheduler.rst diff --git a/docs/system/time-zone.rst b/docs/configuration/system/time-zone.rst index 025c4376..025c4376 100644 --- a/docs/system/time-zone.rst +++ b/docs/configuration/system/time-zone.rst diff --git a/docs/configuration/system/wifi-requlatory-domain.disable b/docs/configuration/system/wifi-requlatory-domain.disable new file mode 100644 index 00000000..2b6ce7d4 --- /dev/null +++ b/docs/configuration/system/wifi-requlatory-domain.disable @@ -0,0 +1,2 @@ +wifi-requlatory-domain +######################
\ No newline at end of file diff --git a/docs/qos.rst b/docs/configuration/trafficpolicy/index.rst index a4e56665..f3e498d4 100644 --- a/docs/qos.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -1,5 +1,10 @@ .. _qos: +############## +Traffic Policy +############## + + *** QoS *** @@ -114,8 +119,8 @@ 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 +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 @@ -189,7 +194,8 @@ different parameters you can configure. 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`_. +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: @@ -199,12 +205,12 @@ You can also write a description for a filter: -.. 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:: 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 +.. note:: IPv6 TCP filters will only match IPv6 packets with no header + extension, see https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers Default @@ -245,9 +251,9 @@ possibilities depending on the Traffic Policy you are configuring. 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. +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`: @@ -336,12 +342,11 @@ you will only be able to apply one policy per interface and direction 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 do not know what policy you need, you might consider FQ-CoDel_ as - your multipurpose nearly-no-configuration low-delay fair-queue - policy; if delay does not worry you and you want to manually allocate - bandwidth shares to specific traffic, then you should consider - Shaper_. +.. 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 <embed>` **as FQ-CoDel**. Drop Tail --------- @@ -367,7 +372,8 @@ 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 <policy-name> queue-limit <number-of-packets> +.. cfgcmd:: set traffic-policy drop-tail <policy-name> queue-limit + <number-of-packets> 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 @@ -505,7 +511,8 @@ and increase `interval` to something around 150 ms. persistent queue is developing, ensuring that the measured minimum delay does not become too stale (default: 100ms). -.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit <number-of-packets>` +.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit + <number-of-packets>` 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 @@ -528,8 +535,8 @@ 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 100% - set traffic-policy shaper FQ-CODEL-SHAPER fq-codel + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel @@ -558,7 +565,8 @@ the configured classes. **inbound** traffic, check the ingress-shaping_ section. -.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match <match-name> description <description> +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match + <match-name> description <description> Use this command to configure an Ingress Policer, defining its name, a class identifier (1-4090), a class matching rule name and its @@ -569,14 +577,16 @@ 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 <policy-name> class <class-ID> bandwidth <rate> +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth + <rate> 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 <policy-name> class <class-ID> burst <burst-size> +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> burst + <burst-size> Use this command to configure an Ingress Policer, defining its name, a class identifier (1-4090) and the burst size in bytes for this @@ -595,7 +605,8 @@ how you want matching traffic to behave. and the burst size in bytes (default: 15) for its default policy. -.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority <value> +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority + <value> Use this command to configure an Ingress Policer, defining its name, a class identifier (1-4090), and the priority (0-20, default 20) in @@ -632,7 +643,8 @@ under certain network conditions. Token Bucket Filter qdisc). Default:15kb. It will only take effect if you have configured its bandwidth too. -.. cfgcmd:: set traffic-policy network-emulator <policy-name> network-delay <delay> +.. cfgcmd:: set traffic-policy network-emulator <policy-name> network-delay + <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 @@ -641,26 +653,30 @@ under certain network conditions. configured its bandwidth too. You can use secs, ms and us. Default: 50ms. -.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-corruption <percent> +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-corruption + <percent> 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 <policy-name> packet-loss <percent>` +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-loss + <percent> 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 <policy-name> packet-reordering <percent>` +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-reordering + <percent> 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 <policy-name> queue-limit <limit> +.. cfgcmd:: set traffic-policy network-emulator <policy-name> queue-limit + <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 @@ -731,7 +747,8 @@ setting: Random Early Detection (RED) -.. cfgcmd:: set traffic-policy priority-queue <policy-name> class <class-ID> queue-limit <limit>` +.. cfgcmd:: set traffic-policy priority-queue <policy-name> class <class-ID> + queue-limit <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 @@ -800,7 +817,8 @@ algorithm might be to prevent a backbone overload. But only for TCP 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 <policy-name> precedence <IP-precedence-value> average-packet <bytes> +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> average-packet <bytes> Use this command to configure a Random-Detect policy and set its name, then state the IP Precedence for the virtual queue you are @@ -810,7 +828,8 @@ algorithm might be to prevent a backbone overload. But only for TCP .. note:: When configuring a Random-Detect policy: **the higher the precedence number, the higher the priority**. -.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> mark-probability <value> +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> mark-probability <value> Use this command to configure a Random-Detect policy and set its name, then state the IP Precedence for the virtual queue you are @@ -818,7 +837,8 @@ algorithm might be to prevent a backbone overload. But only for TCP probability by giving the N value of the fraction 1/N (default: 10). -.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> maximum-threshold <packets> +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> maximum-threshold <packets> Use this command to configure a Random-Detect policy and set its name, then state the IP Precedence for the virtual queue you are @@ -826,7 +846,8 @@ algorithm might be to prevent a backbone overload. But only for TCP be (from 0 to 4096 packets, default: 18). At this size, the marking (drop) probability is maximal. -.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> minimum-threshold <packets> +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> minimum-threshold <packets> Use this command to configure a Random-Detect policy and set its name, then state the IP Precedence for the virtual queue you are @@ -858,7 +879,8 @@ The default values for the minimum-threshold depend on IP precedence: +------------+-----------------------+ -.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> queue-limit <packets> +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> queue-limit <packets> Use this command to configure a Random-Detect policy and set its name, then name the IP Precedence for the virtual queue you are @@ -1019,25 +1041,29 @@ the higher the priority. and the maximum bandwidth for all combined traffic. -.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> bandwidth <rate> +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> bandwidth + <rate> 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 <policy-name> class <class-ID> burst <bytes> +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> burst + <bytes> 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 <policy-name> class <class-ID> ceiling <bandwidth> +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> ceiling + <bandwidth> 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 <policy-name> class <class-ID> priority <0-7> +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> 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 @@ -1084,9 +1110,9 @@ parameters. .. note:: If you configure a class for **VoIP traffic**, don't give it any - *ceiling*, otherwise new VoIP calls could start when there is available - bandwidth and get suddenly dropped when other classes start using - their bandwidth. + *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 @@ -1183,11 +1209,20 @@ That is how it is possible to do the so-called "ingress shaping". 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``. +.. stop_vyoslinter + .. _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 + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst new file mode 100644 index 00000000..f902c388 --- /dev/null +++ b/docs/configuration/vpn/dmvpn.rst @@ -0,0 +1,336 @@ +.. _vpn-dmvpn: + +##### +DMVPN +##### + +:abbr:`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +:abbr:`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +* :abbr:`NHRP (Next Hop Resolution Protocol)` :rfc:`2332` +* :abbr:`mGRE (Multipoint Generic Routing Encapsulation)` :rfc:`1702` +* :abbr:`IPSec (IP Security)` - too many RFCs to list, but start with + :rfc:`4301` + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A + complete solution also incorporates the use of a routing protocol. BGP is + particularly well suited for use with DMVPN. + +.. figure:: /_static/images/vpn_dmvpn_topology01.png + :scale: 40 % + :alt: Baseline DMVPN topology + + Baseline DMVPN topology + +************* +Configuration +************* + +* Please refer to the :ref:`tunnel-interface` documentation for the individual + tunnel related options. + +* Please refer to the :ref:`ipsec` documentation for the individual IPSec + related options. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> cisco-authentication <secret> + + Enables Cisco style authentication on NHRP packets. This embeds the secret + plaintext password to the outgoing NHRP packets. Incoming NHRP packets on + this interface are discarded unless the secret password is present. Maximum + length of the secret is 8 characters. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> dynamic-map <address> + nbma-domain-name <fqdn> + + Specifies that the :abbr:`NBMA (Non-broadcast multiple-access network)` + addresses of the next hop servers are defined in the domain name + nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry. + + Each dynamic NHS will get a peer entry with the configured network address + and the discovered NBMA address. + + The first registration request is sent to the protocol broadcast address, and + the server's real protocol address is dynamically detected from the first + registration reply. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map cisco + + If the statically mapped peer is running Cisco IOS, specify the cisco keyword. + It is used to fix statically the Registration Request ID so that a matching + Purge Request can be sent if NBMA address has changed. This is to work around + broken IOS which requires Purge Request ID to match the original Registration + Request ID. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map nbma-address <address> + + Creates static peer mapping of protocol-address to :abbr:`NBMA (Non-broadcast + multiple-access network)` address. + + If the IP prefix mask is present, it directs opennhrp to use this peer as a + next hop server when sending Resolution Requests matching this subnet. + + This is also known as the HUBs IP address or FQDN. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map register + + The optional parameter register specifies that Registration Request should be + sent to this peer on startup. + + This option is required when running a DMVPN spoke. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> multicast <dynamic | nhs> + + Determines how opennhrp daemon should soft switch the multicast traffic. + Currently, multicast traffic is captured by opennhrp daemon using a packet + socket, and resent back to proper destinations. This means that multicast + packet sending is CPU intensive. + + Specfying nhs makes all multicast packets to be repeated to each statically + configured next hop. + + Synamic instructs to forward to all peers which we have a direct connection + with. Alternatively, you can specify the directive multiple times for each + protocol-address the multicast traffic should be sent to. + + .. warning:: It is very easy to misconfigure multicast repeating if you have + multiple NHSes. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> non-caching + + Disables caching of peer information from forwarded NHRP Resolution Reply + packets. This can be used to reduce memory consumption on big NBMA subnets. + + .. note:: Currently does not do much as caching is not implemented. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> redirect + + Enable sending of Cisco style NHRP Traffic Indication packets. If this is + enabled and opennhrp detects a forwarded packet, it will send a message to + the original sender of the packet instructing it to create a direct connection + with the destination. This is basically a protocol independent equivalent of + ICMP redirect. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut + + Enable creation of shortcut routes. + + A received NHRP Traffic Indication will trigger the resolution and + establishment of a shortcut route. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-destination + + This instructs opennhrp to reply with authorative answers on NHRP Resolution + Requests destinied to addresses in this interface (instead of forwarding the + packets). This effectively allows the creation of shortcut routes to subnets + located on the interface. + + When specified, this should be the only keyword for the interface. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + + Defines an off-NBMA network prefix for which the GRE interface will act as a + gateway. This an alternative to defining local interfaces with + shortcut-destination flag. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +******* +Example +******* + + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was build using :abbr:`EVE-NG (Emulated Virtual +Environment NG)`. + +.. figure:: /_static/images/blueprint-dmvpn.png + :alt: DMVPN network + + DMVPN example network + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address `192.0.2.1` is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +Configuration +============= + +Hub +--- + +.. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + + set interfaces tunnel tun100 address '172.16.253.134/29' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '192.0.2.1' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 multicast 'dynamic' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'transport' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + +.. note:: Setting this up on AWS will require a "Custom Protocol Rule" for + protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC + Network ACL, and secondly on the security group network ACL attached to the + EC2 instance. This has been tested as working for the official AMI image on + the AWS Marketplace. (Locate the correct VPC and security group by navigating + through the details pane below your EC2 instance in the AWS console). + +Spoke +----- + +The individual spoke configurations only differ in the local IP address on the +``tun10`` interface. See the above diagram for the individual IP addresses. + +spoke01-spoke04 +^^^^^^^^^^^^^^^ + +.. code-block:: none + + crypto keyring DMVPN + pre-shared-key address 192.0.2.1 key secret + ! + crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + crypto isakmp invalid-spi-recovery + crypto isakmp keepalive 30 30 periodic + crypto isakmp profile DMVPN + keyring DMVPN + match identity address 192.0.2.1 255.255.255.255 + ! + crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport + ! + crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + set isakmp-profile DMVPN + ! + interface Tunnel10 + ! individual spoke tunnel IP must change + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication secret + ip nhrp map 172.16.253.134 192.0.2.1 + ip nhrp map multicast 192.0.2.1 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source FastEthernet0/0 + tunnel mode gre multipoint + tunnel key 1 + ! + interface FastEthernet0/0 + ip address dhcp + duplex half + + +spoke05 +^^^^^^^ + +VyOS can also run in DMVPN spoke mode. + +.. code-block:: none + + set interfaces ethernet eth0 address 'dhcp' + + set interfaces tunnel tun100 address '172.16.253.133/29' + set interfaces tunnel tun100 local-ip 0.0.0.0 + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 register + set protocols nhrp tunnel tun100 multicast 'nhs' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'transport' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB close-action 'none' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + + diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst new file mode 100644 index 00000000..abaca198 --- /dev/null +++ b/docs/configuration/vpn/index.rst @@ -0,0 +1,26 @@ +### +VPN +### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec + l2tp + openconnect + pptp + rsa-keys + sstp + + + +pages to sort + +.. toctree:: + :maxdepth: 1 + :includehidden: + + dmvpn + site2site_ipsec
\ No newline at end of file diff --git a/docs/vpn/gre-ipsec.rst b/docs/configuration/vpn/ipsec.rst index 6d4bf1d0..2888336c 100644 --- a/docs/vpn/gre-ipsec.rst +++ b/docs/configuration/vpn/ipsec.rst @@ -1,11 +1,12 @@ -.. _gre-ipsec: +.. _ipsec: -GRE/IPsec ---------- +##### +IPsec +##### -Generic Routing Encapsulation (GRE), GRE/IPsec (or IPIP/IPsec, SIT/IPsec, or any -other stateless tunnel protocol over IPsec) is the usual way to protect the -traffic inside a tunnel. +:abbr:`GRE (Generic Routing Encapsulation)`, GRE/IPsec (or IPIP/IPsec, +SIT/IPsec, or any other stateless tunnel protocol over IPsec) is the usual way +to protect the traffic inside a tunnel. An advantage of this scheme is that you get a real interface with its own address, which makes it easier to setup static routes or use dynamic routing @@ -25,11 +26,12 @@ what needs to be changed to make it work with a different protocol. We assume that IPsec will use pre-shared secret authentication and will use AES128/SHA1 for the cipher and hash. Adjust this as necessary. -.. NOTE:: VMware users should ensure that VMXNET3 adapters used, e1000 adapters - have known issue with GRE processing +.. NOTE:: VMware users should ensure that a VMXNET3 adapter is used. E1000 + adapters have known issues with GRE processing. +************************* IPsec policy matching GRE -^^^^^^^^^^^^^^^^^^^^^^^^^ +************************* The first and arguably cleaner option is to make your IPsec policy match GRE packets between external addresses of your routers. This is the best option if @@ -181,7 +183,7 @@ On the RIGHT (dynamic address): set vpn ipsec site-to-site peer 192.0.2.10 authentication id @RIGHT set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa-key-name LEFT - set vpn ipsec site-to-site peer 192.0.2.10 remote-id @LEFT + set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup diff --git a/docs/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 0d8dde08..0df5080c 100644 --- a/docs/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -72,12 +72,8 @@ parameter to the client. .. code-block:: none - set vpn l2tp remote-access dns-servers server-1 '8.8.8.8' - set vpn l2tp remote-access dns-servers server-2 '8.8.4.4' - -.. note:: Those are the `Google public DNS`_ servers, but you can choose - any public available servers, like Quad9_ (9.9.9.9), Cloudflare_ (1.1.1.1) - or OpenNIC_. + set vpn l2tp remote-access name-server '198.51.100.8' + set vpn l2tp remote-access name-server '198.51.100.4' Established sessions can be viewed using the **show vpn remote-access** operational command, or **show l2tp-server sessions** @@ -107,11 +103,11 @@ Below is an example to configure a LNS: set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication local-users username test password 'test' -The example above uses 192.0.2.2 as external IP address. A LAC normally -requires an authentication password, which is set in the example configuration -to ``lns shared-secret 'secret'``. This setup requires the Compression Control -Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access ccp-disable`` -accomplishes that. +The example above uses 192.0.2.2 as external IP address. A LAC normally requires +an authentication password, which is set in the example configuration to +``lns shared-secret 'secret'``. This setup requires the Compression Control +Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access +ccp-disable`` accomplishes that. Bandwidth Shaping @@ -166,9 +162,9 @@ servers can be setup and will be used subsequentially. RADIUS source address ^^^^^^^^^^^^^^^^^^^^^ -If you are using OSPF as IGP always the closets interface connected to the RADIUS -server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests to a -single source IP e.g. the loopback interface. +If you are using OSPF as IGP always the closets interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. .. code-block:: none @@ -183,14 +179,15 @@ on this NAS. RADIUS bandwidth shaping attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To enable bandwidth shaping via RADIUS, the option rate-limit needs to be enabled. +To enable bandwidth shaping via RADIUS, the option rate-limit needs to be +enabled. .. code-block:: none set vpn l2tp remote-access authentication radius rate-limit enable -The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may also -redefine it. +The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may +also redefine it. .. code-block:: none diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst new file mode 100644 index 00000000..feb0bab1 --- /dev/null +++ b/docs/configuration/vpn/openconnect.rst @@ -0,0 +1,95 @@ +.. _vpn-openconnect: + +########### +OpenConnect +########### + +OpenConnect-compatible server feature is available from this release. +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the network. + +.. note:: All certificates should be stored on VyOS under /config/auth. If + certificates are not stored in the /config directory they will not be + migrated during a software update. + +************* +Configuration +************* + +SSL Certificates +================ + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following command +will create a self signed certificates and will be stored in the file path +`/config/auth`. + +.. code-block:: none + + openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt + openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt + +We can also create the certificates using Cerbort which is an easy-to-use client +that fetches a certificate from Let's Encrypt an open certificate authority +launched by the EFF, Mozilla, and others and deploys it to a web server. + +.. code-block:: none + + sudo certbot certonly --standalone --preferred-challenges http -d <domain name> + +Server Configuration +==================== + +.. code-block:: none + + set vpn openconnect authentication local-users username <user> password <pass> + set vpn openconnect authentication mode <local|radius> + set vpn opneconnect network-settings client-ip-settings subnet <subnet> + set vpn openconnect network-settings name-server <address> + set vpn openconnect network-settings name-server <address> + set vpn openconnect ssl ca-cert-file <file> + set vpn openconnect ssl cert-file <file> + set vpn openconnect ssl key-file <file> + + +******* +Example +******* + +Use local user name "user4" with password "SecretPassword" +Client IP addresses will be provided from pool 100.64.0.0/24 +The Gateway IP Address must be in one of the router´s interfaces. + +.. code-block:: none + + set vpn openconnect authentication local-users username user4 password 'SecretPassword' + set vpn openconnect authentication mode 'local' + set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn openconnect network-settings name-server '10.1.1.1' + set vpn openconnect network-settings name-server '10.1.1.2' + set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' + set vpn openconnect ssl cert-file '/config/auth/cert.pem' + set vpn openconnect ssl key-file '/config/auth/privkey.pem' + + +************ +Verification +************ + +.. code-block:: none + + + vyos@RTR1:~$ show openconnect-server sessions + + interface username ip remote IP RX TX state uptime + ----------- ---------- ------------ ------------- -------- -------- --------- -------- + sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s + +.. note:: It is compatible with Cisco (R) AnyConnect (R) clients. diff --git a/docs/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 72b3feb0..12364acb 100644 --- a/docs/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst @@ -3,11 +3,15 @@ PPTP-Server ----------- -The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only for backwards compatibility. -PPTP has many well known security issues and you should use one of the many other new VPN implementations. +The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only +for backwards compatibility. PPTP has many well known security issues and you +should use one of the many other new VPN implementations. -As per default and if not otherwise defined, mschap-v2 is being used for authentication and mppe 128-bit (stateless) for encryption. -If no gateway-address is set within the configuration, the lowest IP out of the /24 client-ip-pool is being used. For instance, in the example below it would be 192.168.0.1. +As per default and if not otherwise defined, mschap-v2 is being used for +authentication and mppe 128-bit (stateless) for encryption. If no +gateway-address is set within the configuration, the lowest IP out of the /24 +client-ip-pool is being used. For instance, in the example below it would be +192.168.0.1. server example ^^^^^^^^^^^^^^ @@ -25,7 +29,8 @@ server example client example (debian 9) ^^^^^^^^^^^^^^^^^^^^^^^^^ -Install the client software via apt and execute pptpsetup to generate the configuration. +Install the client software via apt and execute pptpsetup to generate the +configuration. .. code-block:: none diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst new file mode 100644 index 00000000..7912cffe --- /dev/null +++ b/docs/configuration/vpn/rsa-keys.rst @@ -0,0 +1,88 @@ + +######## +RSA-Keys +######## +RSA can be used for services such as key exchanges and for encryption purposes. +To make IPSec work with dynamic address on one/both sides, we will have to use +RSA keys for authentication. They are very fast and easy to setup. + +First, on both routers run the operational command “generate vpn rsa-key +bits 2048”. You may choose different length than 2048 of course. + +.. code-block:: none + + vyos@left# run generate vpn rsa-key bits 2048 + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Please note down this public key, as you have to add this RSA key in the opposite router. + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. The key points: + +1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point #3 to work. +5. Don't forget to enable NAT traversal on both sides, "set vpn ipsec nat-traversal enable". + +LEFT SIDE: + +.. code-block:: none + + set vpn rsa-keys rsa-key-name RIGHT rsa-key <PUBLIC KEY FROM THE RIGHT> + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal 'enable' + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer 192.0.2.60 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.60 authentication id @LEFT + set vpn ipsec site-to-site peer 192.0.2.60 authentication rsa-key-name RIGHT + set vpn ipsec site-to-site peer 192.0.2.60 authentication remote-id RIGHT + set vpn ipsec site-to-site peer 192.0.2.60 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.60 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.60 local-address any + set vpn ipsec site-to-site peer 192.0.2.60 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.60 tunnel 1 local prefix 192.168.99.1/32 + set vpn ipsec site-to-site peer 192.0.2.60 tunnel 1 remote prefix 192.168.99.2/32 + +RIGHT SIDE: + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key <PUBLIC KEY FROM THE LEFT> + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal 'enable' + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer @LEFT authentication id @RIGHT + set vpn ipsec site-to-site peer @LEFT authentication mode rsa + set vpn ipsec site-to-site peer @LEFT authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer @LEFT connection-type respond + set vpn ipsec site-to-site peer @LEFT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer @LEFT ike-group MyIKEGroup + set vpn ipsec site-to-site peer @LEFT local-address any + set vpn ipsec site-to-site peer @LEFT tunnel 1 local prefix 192.168.99.2/32 + set vpn ipsec site-to-site peer @LEFT tunnel 1 remote prefix 192.168.99.1/32 + diff --git a/docs/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst index 08ccc648..e81c5c3b 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -3,103 +3,151 @@ Site-to-Site ============ -Site-to-site mode provides a way to add remote peers, which could be configured to exchange encrypted information between them and VyOS itself or connected/routed networks. +Site-to-site mode provides a way to add remote peers, which could be configured +to exchange encrypted information between them and VyOS itself or +connected/routed networks. -To configure site-to-site connection you need to add peers with the ``set vpn ipsec site-to-site`` command. +To configure site-to-site connection you need to add peers with the +``set vpn ipsec site-to-site`` command. You can identify a remote peer with: -* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used when a peer has a public static IP address; -* Hostname. This mode is similar to IP address, only you define DNS name instead of an IP. Could be used when a peer has a public IP address and DNS name, but an IP address could be changed from time to time; -* Remote ID of the peer. In this mode, there is no predefined remote address nor DNS name of the peer. This mode is useful when a peer doesn't have a publicly available IP address (NAT between it and VyOS), or IP address could be changed. +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used + when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead + of an IP. Could be used when a peer has a public IP address and DNS name, but + an IP address could be changed from time to time; +* Remote ID of the peer. In this mode, there is no predefined remote address + nor DNS name of the peer. This mode is useful when a peer doesn't have a + publicly available IP address (NAT between it and VyOS), or IP address could + be changed. Each site-to-site peer has the next options: -* ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: +* ``authentication`` - configure authentication between VyOS and a remote peer. + Suboptions: - * ``id`` - ID for the local VyOS router. If defined, during the authentication it will be send to remote peer; + * ``id`` - ID for the local VyOS router. If defined, during the authentication + it will be send to remote peer; * ``mode`` - mode for authentication between VyOS and remote peer: - * ``pre-shared-secret`` - use predefined shared secret phrase, must be the same for local and remote side; + * ``pre-shared-secret`` - use predefined shared secret phrase, must be the + same for local and remote side; - * ``rsa`` - use simple shared RSA key. The key must be defined in the ``set vpn rsa-keys`` section; + * ``rsa`` - use simple shared RSA key. The key must be defined in the + ``set vpn rsa-keys`` section; * ``x509`` - use certificates infrastructure for authentication. - * ``pre-shared-secret`` - predefined shared secret. Used if configured ``mode pre-shared-secret``; + * ``pre-shared-secret`` - predefined shared secret. Used if configured + ``mode pre-shared-secret``; - * ``remote-id`` - define an ID for remote peer, instead of using peer name or address. Useful in case if the remote peer is behind NAT or if ``mode x509`` is used; + * ``remote-id`` - define an ID for remote peer, instead of using peer name or + address. Useful in case if the remote peer is behind NAT or if ``mode x509`` + is used; - * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined in the ``set vpn rsa-keys`` section; + * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined + in the ``set vpn rsa-keys`` section; - * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when ``id`` is defined; + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when + ``id`` is defined; * ``x509`` - options for x509 authentication mode: - * ``ca-cert-file`` - CA certificate file. Using for authenticating remote peer; + * ``ca-cert-file`` - CA certificate file. Using for authenticating + remote peer; - * ``cert-file`` - certificate file, which will be used for authenticating local router on remote peer; + * ``cert-file`` - certificate file, which will be used for authenticating + local router on remote peer; - * ``crl-file`` - file with the Certificate Revocation List. Using to check if a certificate for the remote peer is valid or revoked; + * ``crl-file`` - file with the Certificate Revocation List. Using to check if + a certificate for the remote peer is valid or revoked; - * ``key`` - a private key, which will be used for authenticating local router on remote peer: + * ``key`` - a private key, which will be used for authenticating local router + on remote peer: * ``file`` - path to the key file; * ``password`` - passphrase private key, if needed. -* ``connection-type`` - how to handle this connection process. Possible variants: +* ``connection-type`` - how to handle this connection process. Possible + variants: - * ``initiate`` - do initial connection to remote peer immediately after configuring and after boot. In this mode the connection will not be restarted in case of disconnection, therefore should be used only together with DPD or another session tracking methods; + * ``initiate`` - do initial connection to remote peer immediately after + configuring and after boot. In this mode the connection will not be restarted + in case of disconnection, therefore should be used only together with DPD or + another session tracking methods; - * ``respond`` - do not try to initiate a connection to a remote peer. In this mode, the IPSec session will be established only after initiation from a remote peer. Could be useful when there is no direct connectivity to the peer due to firewall or NAT in the middle of the local and remote side. + * ``respond`` - do not try to initiate a connection to a remote peer. In this + mode, the IPSec session will be established only after initiation from a + remote peer. Could be useful when there is no direct connectivity to the + peer due to firewall or NAT in the middle of the local and remote side. -* ``default-esp-group`` - ESP group to use by default for traffic encryption. Might be overwritten by individual settings for tunnel or VTI interface binding; +* ``default-esp-group`` - ESP group to use by default for traffic encryption. + Might be overwritten by individual settings for tunnel or VTI interface + binding; * ``description`` - description for this peer; -* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec connection with this peer, instead of ``local-address``; +* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec + connection with this peer, instead of ``local-address``; -* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. Useful in case if between local and remote side is firewall or NAT, which not allows passing plain ESP packets between them; +* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. + Useful in case if between local and remote side is firewall or NAT, which not + allows passing plain ESP packets between them; * ``ike-group`` - IKE group to use for key exchanges; -* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. Can be used only with IKEv2: +* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. + Can be used only with IKEv2: - * ``yes`` - create a new IKE_SA from the scratch and try to recreate all IPsec SAs; + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all + IPsec SAs; * ``no`` - rekey without uninstalling the IPsec SAs; * ``inherit`` - use default behavior for the used IKE group. -* ``local-address`` - local IP address for IPSec connection with this peer. If defined ``any``, then an IP address which configured on interface with default route will be used; +* ``local-address`` - local IP address for IPSec connection with this peer. + If defined ``any``, then an IP address which configured on interface with + default route will be used; -* ``tunnel`` - define criteria for traffic to be matched for encrypting and send it to a peer: +* ``tunnel`` - define criteria for traffic to be matched for encrypting and send + it to a peer: * ``disable`` - disable this tunnel; * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; - * ``local`` - define a local source for match traffic, which should be encrypted and send to this peer: + * ``local`` - define a local source for match traffic, which should be + encrypted and send to this peer: * ``port`` - define port. Have effect only when used together with ``prefix``; * ``prefix`` - IP network at local side. - * ``protocol`` - define the protocol for match traffic, which should be encrypted and send to this peer; + * ``protocol`` - define the protocol for match traffic, which should be + encrypted and send to this peer; - * ``remote`` - define the remote destination for match traffic, which should be encrypted and send to this peer: + * ``remote`` - define the remote destination for match traffic, which should be + encrypted and send to this peer: * ``port`` - define port. Have effect only when used together with ``prefix``; * ``prefix`` - IP network at remote side. -* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will be send to VTI interface will be encrypted and send to this peer. Using VTI makes IPSec configuration much flexible and easier in complex situation, and allows to dynamically add/delete remote networks, reachable via a peer, as in this mode router don't need to create additional SA/policy for each remote network: +* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will + be send to VTI interface will be encrypted and send to this peer. Using VTI + makes IPSec configuration much flexible and easier in complex situation, and + allows to dynamically add/delete remote networks, reachable via a peer, as in + this mode router don't need to create additional SA/policy for each remote + network: * ``bind`` - select a VTI interface to bind to this peer; - * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI interface. + * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI + interface. Examples: ------------------ @@ -218,7 +266,7 @@ IKEv2 Imagine the following topology -.. figure:: ../_static/images/vpn_s2s_ikev2.png +.. figure:: /_static/images/vpn_s2s_ikev2.png :scale: 50 % :alt: IPSec IKEv2 site2site VPN diff --git a/docs/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index de13b5ae..3600681f 100644 --- a/docs/vpn/sstp.rst +++ b/docs/configuration/vpn/sstp.rst @@ -23,9 +23,11 @@ certificates as well as a private PKI is required. certificates are not stored in the ``/config`` directory they will not be migrated during a software update. +Certificates +============ -Self Signed CA and Certificates -=============================== +Self Signed CA +-------------- To generate the CA, the server private key and certificates the following commands can be used. @@ -62,7 +64,8 @@ commands can be used. Configuration ============= -.. cfgcmd:: set vpn sstp authentication local-users username <user> password <pass> +.. cfgcmd:: set vpn sstp authentication local-users username <user> password + <pass> Create `<user>` for local authentication on this system. The users password will be set to `<pass>`. @@ -71,19 +74,23 @@ Configuration Disable `<user>` account. -.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip <address> +.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip + <address> Assign static IP address to `<user>` account. -.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit download <bandwidth> +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + download <bandwidth> Download bandwidth limit in kbit/s for `<user>`. -.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit upload <bandwidth> +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + upload <bandwidth> Upload bandwidth limit in kbit/s for `<user>`. -.. cfgcmd:: set vpn sstp authentication protocols <pap | chap | mschap | mschap-v2> +.. cfgcmd:: set vpn sstp authentication protocols + <pap | chap | mschap | mschap-v2> Require the peer to authenticate itself using one of the following protocols: pap, chap, mschap, mschap-v2. @@ -98,18 +105,18 @@ Configuration * **local**: All authentication queries are handled locally. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings gateway-address <gateway> +.. cfgcmd:: set vpn sstp gateway-address <gateway> Specifies single `<gateway>` IP address to be used as local address of PPP interfaces. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings subnet <subnet> +.. cfgcmd:: set vpn sstp client-ip-pool subnet <subnet> Use `<subnet>` as the IP pool for all connecting clients. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool prefix <address> mask <number-of-bits> +.. cfgcmd:: set vpn sstp client-ipv6-pool prefix <address> mask <number-of-bits> Use this comand to set the IPv6 address pool from which an SSTP client will get an IPv6 prefix of your defined length (mask) to terminate the @@ -117,7 +124,8 @@ Configuration bit long, the default value is 64. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> +.. cfgcmd:: set vpn sstp client-ipv6-pool delegate <address> delegation-prefix + <number-of-bits> Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You will have to set your IPv6 pool and the length of the @@ -126,7 +134,7 @@ Configuration delegation prefix can be set from 32 to 64 bit long. -.. cfgcmd:: set vpn sstp network-settings name-server <address> +.. cfgcmd:: set vpn sstp name-server <address> Connected client should use `<address>` as their DNS server. This command accepts both IPv4 and IPv6 addresses. Up to two nameservers @@ -152,23 +160,23 @@ SSL Certificates PPP Settings ------------ -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-failure <number> +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure <number> Defines the maximum `<number>` of unanswered echo requests. Upon reaching the value `<number>`, the session will be reset. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-interval <interval> +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval <interval> If this option is specified and is greater than 0, then the PPP module will send LCP pings of the echo request every `<interval>` seconds. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-timeout +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout Specifies timeout in seconds to wait for any peer activity. If this option specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" is not used. -.. cfgcmd:: set vpn sstp ppp-settings mppe <require | prefer | deny> +.. cfgcmd:: set vpn sstp ppp-options mppe <require | prefer | deny> Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotioation preference. @@ -269,15 +277,15 @@ Example .. code-block:: none - set vpn sstp authentication local-users username foo password 'bar' - set vpn sstp authentication mode 'local' - set vpn sstp network-settings client-ip-settings gateway-address '192.0.2.254' - set vpn sstp network-settings client-ip-settings subnet '192.0.2.0/25' - set vpn sstp network-settings name-server '10.0.0.1' - set vpn sstp network-settings name-server '10.0.0.2' - set vpn sstp ssl ca-cert-file '/config/auth/ca.crt' - set vpn sstp ssl cert-file '/config/auth/server.crt' - set vpn sstp ssl key-file '/config/auth/server.key' + set vpn sstp authentication local-users username vyos password vyos + set vpn sstp authentication mode local + set vpn sstp gateway-address 192.0.2.254 + set vpn sstp client-ip-pool subnet 192.0.2.0/25 + set vpn sstp name-server 10.0.0.1 + set vpn sstp name-server 10.0.0.2 + set vpn sstp ssl ca-cert-file /config/auth/ca.crt + set vpn sstp ssl cert-file /config/auth/server.crt + set vpn sstp ssl key-file /config/auth/server.key Testing SSTP ============ @@ -342,4 +350,4 @@ A connection attempt will be shown as: .. _sstpc: https://github.com/reliablehosting/sstp-client -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/vrf.rst b/docs/configuration/vrf/index.rst index 75075be6..244784de 100644 --- a/docs/vrf.rst +++ b/docs/configuration/vrf/index.rst @@ -23,8 +23,8 @@ then enslaved to a VRF device. .. cfgcmd:: set vrf name <name> - Create new VRF instance with `<name>`. The name is used when placing individual - interfaces into the VRF. + Create new VRF instance with `<name>`. The name is used when placing + individual interfaces into the VRF. .. cfgcmd:: set vrf name <name> table <id> @@ -50,7 +50,8 @@ Interfaces When VRFs are used it is not only mandatory to create a VRF but also the VRF itself needs to be assigned to an interface. -.. cfgcmd:: set interfaces <dummy | ethernet | bonding | bridge | pppoe> <interface> vrf <name> +.. cfgcmd:: set interfaces <dummy | ethernet | bonding | bridge | pppoe> + <interface> vrf <name> Assign interface identified by `<interface>` to VRF named `<name>`. @@ -79,11 +80,13 @@ Static Routes Configure next-hop `<address>` for an IPv4 static route in the VRF identified by `<name>`. Multiple static routes can be created. -.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> disable +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + disable Disable IPv4 static route entry in the VRF identified by `<name>` -.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> distance <distance> +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -95,11 +98,13 @@ Static Routes Configure next-hop `<address>` for an IPv6 static route in the VRF identified by `<name>`. Multiple IPv6 static routes can be created. -.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> disable +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + disable Disable IPv6 static route entry in the VRF identified by `<name>`. -.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> distance <distance> +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -113,14 +118,16 @@ Static Routes Leaking """"""" -.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> next-hop-vrf <default | vrf-name> +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + vrf <default | vrf-name> Use this command if you have shared services or routes that should be shared between multiple VRF instances. This will add an IPv4 route to VRF `<name>` routing table to reach a `<subnet>` via a next-hop gatewys `<address>` in a different VRF or leak it into the default VRF. -.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> next-hop-vrf <default | vrf-name> +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + vrf <default | vrf-name> Use this command if you have shared services or routes that should be shared between multiple VRF instances. This will add an IPv6 route to VRF `<name>` @@ -131,34 +138,40 @@ Leaking Interface Routes """""""""""""""" -.. cfgcmd:: set protocols vrf <name> static interface-route <subnet> next-hop-interface <interface> +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> Allows you to configure the next-hop interface for an interface-based IPv4 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols vrf <name> static interface-route <subnet> next-hop-interface <interface> disable +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> disable Disables interface-based IPv4 static route. -.. cfgcmd:: set protocols vrf <name> static interface-route <subnet> next-hop-interface <interface> distance <distance> +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. Range is 1 to 255, default is 1. -.. cfgcmd:: set protocols vrf <name> static interface-route6 <subnet> next-hop-interface <interface> +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> Allows you to configure the next-hop interface for an interface-based IPv6 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols vrf <name> static interface-route6 <subnet> next-hop-interface <interface> disable +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> disable Disables interface-based IPv6 static route. -.. cfgcmd:: set protocols vrf <name> static interface-route6 <subnet> next-hop-interface <interface> distance <distance> +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -176,7 +189,8 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols vrf <name> static route <subnet> blackhole distance <distance> +.. cfgcmd:: set protocols vrf <name> static route <subnet> blackhole distance + <distance> Defines blackhole distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -189,7 +203,8 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols vrf <name> static route6 <subnet> blackhole distance <distance> +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> blackhole distance + <distance> Defines blackhole distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -210,11 +225,11 @@ For VR Fmaintenance the followin operational commands are in place. vyos@vyos:~$ show vrf VRF name state mac address flags interfaces -------- ----- ----------- ----- ---------- - blue up de:c4:83:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 - red up be:36:ce:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 + red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 - .. note:: Command should probably be extended to list also the real interfaces - assigned to this one VRF to get a better overview. + .. note:: Command should probably be extended to list also the real + interfaces assigned to this one VRF to get a better overview. .. opcmd:: show vrf <name> @@ -223,7 +238,7 @@ For VR Fmaintenance the followin operational commands are in place. vyos@vyos:~$ show vrf name blue VRF name state mac address flags interfaces -------- ----- ----------- ----- ---------- - blue up de:c4:83:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 .. opcmd:: show ip route vrf <name> @@ -304,4 +319,4 @@ For VR Fmaintenance the followin operational commands are in place. useful when the host specified is a hostname rather than an IP address. -.. include:: common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/configuration/zonepolicy/index.rst b/docs/configuration/zonepolicy/index.rst new file mode 100644 index 00000000..8fe18778 --- /dev/null +++ b/docs/configuration/zonepolicy/index.rst @@ -0,0 +1,71 @@ + +########### +Zone Policy +########### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + +In zone-based policy, interfaces are assigned to zones, and inspection policy is applied to traffic moving between the zones and acted on according to firewall rules. +A Zone is a group of interfaces that have similar functions or features. It establishes the security borders of a network. +A zone defines a boundary where traffic is subjected to policy restrictions as it crosses to another region of a network. + +Key Points: + +* A zone must be configured before an interface is assigned to it and an interface can be assigned to only a single zone. +* All traffic to and from an interface within a zone is permitted. +* All traffic between zones is affected by existing policies +* Traffic cannot flow between zone member interface and any interface that is not a zone member. +* You need 2 separate firewalls to define traffic: one for each direction. + +Example: LAN Network is given SSH access to VyOS box. + +Firewall rules: + +.. code-block:: none + + set firewall name lan-local default-action 'drop' + set firewall name lan-local rule 1 action 'accept' + set firewall name lan-local rule 1 state established 'enable' + set firewall name lan-local rule 1 state related 'enable' + set firewall name lan-local rule 2 action 'drop' + set firewall name lan-local rule 2 state invalid 'enable' + set firewall name lan-local rule 2 log enable + set firewall name lan-local rule 100 action 'accept' + set firewall name lan-local rule 100 destination port '22' + set firewall name lan-local rule 100 log 'enable' + set firewall name lan-local rule 100 protocol 'tcp' + set firewall name local-lan default-action 'drop' + set firewall name local-lan rule 1 action 'accept' + set firewall name local-lan rule 1 state established 'enable' + set firewall name local-lan rule 1 state related 'enable' + set firewall name local-lan rule 2 action 'drop' + set firewall name local-lan rule 2 state invalid 'enable' + set firewall name local-lan rule 2 log enable + set firewall name local-lan rule 100 action 'accept' + set firewall name local-lan rule 100 destination address '192.168.0.0/24' + set firewall name local-lan rule 100 log 'enable' + set firewall name local-lan rule 100 protocol 'tcp' + +Zone-policy Config: + +.. code-block:: none + + set zone-policy zone lan default-action 'drop' + set zone-policy zone lan description 'Local Area Network' + set zone-policy zone lan interface 'eth2' + set zone-policy zone lan from local firewall name 'lan-local' + set zone-policy zone local default-action 'drop' + set zone-policy zone local description 'system-defined zone' + set zone-policy zone local from lan firewall name 'local-lan' + set zone-policy zone local local-zone + +A detailed zone-based policy example is written in the Configuration-Blueprints_ section. + +.. stop_vyoslinter + +.. _Configuration-Blueprints: https://docs.vyos.io/en/latest/configexamples/zone-policy.html + +.. start_vyoslinter diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 43c1e608..cb97e418 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -10,9 +10,9 @@ Prerequisites There are different ways you can build VyOS. -Building using a :ref:`build_docker` container, although not the only way, is the -easiest way as all dependencies are managed for you. However, you can also -set up your own build machine and run a :ref:`build_native`. +Building using a :ref:`build_docker` container, although not the only way, +is the easiest way as all dependencies are managed for you. However, you can +also set up your own build machine and run a :ref:`build_native`. .. note:: Starting with VyOS 1.2 the release model of VyOS has changed. VyOS is now **free as in speech, but not as in beer**. This means that while @@ -93,10 +93,11 @@ The container can also be built directly from source: $ cd vyos-build $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 - $ docker build -t vyos/vyos-build docker # For rolling release + $ docker build -t vyos/vyos-build:current docker # For rolling release -.. note:: Since VyOS has switched to Debian (10) Buster in its ``current`` branch, - you will require individual container for `current` and `crux` builds. +.. note:: Since VyOS has switched to Debian (10) Buster in its ``current`` + branch, you will require individual container for `current` and `crux` + builds. Tips and Tricks --------------- @@ -125,7 +126,7 @@ per release train (`current` or `crux`) - container. Add the following to your -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \ vyos/vyos-build:crux bash' -Now you are prepared with two new aliases ``vybld`` and ``vybld_crux`` to spwan +Now you are prepared with two new aliases ``vybld`` and ``vybld_crux`` to spawn your development containers in your current working directory. .. _build_native: @@ -154,7 +155,7 @@ in the repository_. The ``./configure`` script will also warn you if any dependencies are missing. Once you have the required dependencies installed, you may proceed with the -steps descirbed in :ref:`build_iso`. +steps described in :ref:`build_iso`. .. _build_iso: @@ -175,7 +176,8 @@ Please note as this will differ for both `current` and `crux`. # For VyOS 1.3 (equuleus, current) $ git clone -b current --single-branch https://github.com/vyos/vyos-build -Now a fresh build of the VyOS ISO can begin. Change directory to the ``vyos-build`` directory and run: +Now a fresh build of the VyOS ISO can begin. Change directory to the +``vyos-build`` directory and run: .. code-block:: none @@ -184,7 +186,7 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the ``vyos-buil $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash # For VyOS 1.3 (equuleus, current) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash Start the build: @@ -193,8 +195,8 @@ Start the build: vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 --build-by "j.randomhacker@vyos.io" vyos_bld@d4220bb519a0:/vyos# sudo make iso -When the build is successful, the resulting iso can be found inside the ``build`` -directory as ``live-image-[architecture].hybrid.iso``. +When the build is successful, the resulting iso can be found inside the +``build`` directory as ``live-image-[architecture].hybrid.iso``. Good luck! @@ -202,8 +204,8 @@ Good luck! Docker does not expose all the filesystem feature required to the container. Building within a VirtualBox server on Mac however possible. -.. hint:: Building VyOS on Windows WSL2 with Docker integrated into WSL2 will work - like a charm. No problems are known so far! +.. hint:: Building VyOS on Windows WSL2 with Docker integrated into WSL2 will + work like a charm. No problems are known so far! .. _build source: @@ -257,6 +259,367 @@ The full and current list can be generated with ``./configure --help``: .. _build_custom_packages: +Linux Kernel +============ + +The Linux kernel used by VyOS is heavily tied to the ISO build process. The +file ``data/defaults.json`` hosts a JSON definition of the kernel version used +``kernel_version`` and the ``kernel_flavor`` of the kernel which represents the +kernel's LOCAL_VERSION. Both together form the kernel version variable in the +system: + +.. code-block:: none + + vyos@vyos:~$ uname -r + 4.19.146-amd64-vyos + +Other packages (e.g. vyos-1x) add dependencies to the ISO build procedure on +e.g. the wireguard-modules package which itself adds a dependency on the kernel +version used due to the module it ships. This may change (for WireGuard) in +future kernel releases but as long as we have out-of-tree modules. + +* WireGuard +* Accel-PPP +* Intel NIC drivers +* Inter QAT + +Each of those modules holds a dependency on the kernel version and if you are +lucky enough to receive an ISO build error which sounds like: + +.. code-block:: none + + I: Create initramfs if it does not exist. + Extra argument '4.19.146-amd64-vyos' + Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory] + Options: + -k version Specify kernel version or 'all' + -c Create a new initramfs + -u Update an existing initramfs + -d Remove an existing initramfs + -b directory Set alternate boot directory + -v Be verbose + See update-initramfs(8) for further details. + E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors. + +The most obvious reasons could be: + +* ``vyos-build`` repo is outdated, please ``git pull`` to update to the latest + release kernel version from us. + +* You have your own custom kernel `*.deb` packages in the `packages` folder but + neglected to create all required out-of tree modules like Accel-PPP, + WireGuard, Intel QAT, Intel NIC + +Building The Kernel +------------------- + +The kernel build is quite easy, most of the required steps can be found in the +``vyos-build/packages/linux-kernel/Jenkinsfile`` but we will walk you through +it. + +Clone the kernel source to `vyos-build/packages/linux-kernel/`: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel/ + $ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + +Check out the required kernel version - see ``vyos-build/data/defaults.json`` +file (example uses kernel 4.19.146): + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel/linux + $ git checkout v4.19.146 + Checking out files: 100% (61536/61536), done. + Note: checking out 'v4.19.146'. + + You are in 'detached HEAD' state. You can look around, make experimental + changes and commit them, and you can discard any commits you make in this + state without impacting any branches by performing another checkout. + + If you want to create a new branch to retain commits you create, you may + do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b <new-branch-name> + + HEAD is now at 015e94d0e37b Linux 4.19.146 + +Now we can use the helper script ``build-kernel.sh`` which does all the +necessary voodoo by applying required patches from the +`vyos-build/packages/linux-kernel/patches` folder, copying our kernel +configuration ``x86_64_vyos_defconfig`` to the right location, and finally +building the Debian packages. + +.. note:: Building the kernel will take some time depending on the speed and + quantity of your CPU/cores and disk speed. Expect 20 minutes + (or even longer) on lower end hardware. + +.. code-block:: none + + (18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh + I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch + patching file Documentation/networking/ip-sysctl.txt + patching file include/linux/inetdevice.h + patching file include/linux/ipv6.h + patching file include/uapi/linux/ip.h + patching file include/uapi/linux/ipv6.h + patching file net/ipv4/devinet.c + Hunk #1 succeeded at 2319 (offset 1 line). + patching file net/ipv6/addrconf.c + patching file net/ipv6/route.c + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch + patching file fs/notify/inotify/Kconfig + patching file fs/notify/inotify/inotify_user.c + patching file fs/overlayfs/super.c + Hunk #2 succeeded at 1713 (offset 9 lines). + Hunk #3 succeeded at 1739 (offset 9 lines). + Hunk #4 succeeded at 1762 (offset 9 lines). + patching file include/linux/inotify.h + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch + patching file scripts/package/builddeb + I: make x86_64_vyos_defconfig + HOSTCC scripts/basic/fixdep + HOSTCC scripts/kconfig/conf.o + YACC scripts/kconfig/zconf.tab.c + LEX scripts/kconfig/zconf.lex.c + HOSTCC scripts/kconfig/zconf.tab.o + HOSTLD scripts/kconfig/conf + # + # configuration written to .config + # + I: Generate environment file containing Kernel variable + I: Build Debian Kernel package + UPD include/config/kernel.release + /bin/sh ./scripts/package/mkdebian + dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc + dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos + dpkg-buildpackage: info: source version 4.19.146-1 + dpkg-buildpackage: info: source distribution buster + dpkg-buildpackage: info: source changed by vyos_bld <christian@poessinger.com> + dpkg-buildpackage: info: host architecture amd64 + dpkg-buildpackage: warning: debian/rules is not executable; fixing that + dpkg-source --before-build . + debian/rules build + make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86 KBUILD_BUILD_VERSION=1 KBUILD_SRC= + SYSTBL arch/x86/include/generated/asm/syscalls_32.h + + ... + + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols) + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols) + dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'. + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes + dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list + dpkg-genchanges: info: binary-only upload (no source code included) + dpkg-source --after-build . + dpkg-buildpackage: info: binary-only upload (no source included) + + +In the end you will be presented with the kernel binary packages which you can +then use in your custom ISO build process, by placing all the `*.deb` files in +the vyos-build/packages folder where they will be used automatically when +building VyOS as documented above. + +Firmware +^^^^^^^^ + +If you upgrade your kernel or include new drivers you may need new firmware. +Build a new ``vyos-linux-firmware`` package with the included helper scripts. + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git + $ ./build-linux-firmware.sh + $ cp vyos-linux-firmware_*.deb ../ + +This tries to automatically detect which blobs are needed based on which drivers +were built. If it fails to find the correct files you can add them manually to +``vyos-build/packages/linux-kernel/build-linux-firmware.sh``: + +.. code-block:: bash + + ADD_FW_FILES="iwlwifi* ath11k/QCA6390/*/*.bin" + + +Building Out-Of-Tree Modules +---------------------------- + +Building the kernel is one part, but now you also need to build the required +out-of-tree modules so everything is lined up and the ABIs match. To do so, +you can again take a look at ``vyos-build/packages/linux-kernel/Jenkinsfile`` +to see all of the required modules and their selected versions. We will show +you how to build all the current required modules. + +WireGuard +^^^^^^^^^ + +First, clone the source code and check out the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://salsa.debian.org/debian/wireguard-linux-compat.git + $ cd wireguard-linux-compat + $ git checkout debian/1.0.20200712-1_bpo10+1 + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ ./build-wireguard-modules.sh + I: Apply WireGuard patch: /vyos/packages/linux-kernel/patches/wireguard-linux-compat/0001-Debian-build-wireguard-modules-package.patch + patching file debian/control + patching file debian/rules + I: Build Debian WireGuard package + dpkg-buildpackage: info: source package wireguard-linux-compat + dpkg-buildpackage: info: source version 1.0.20200712-1~bpo10+1 + dpkg-buildpackage: info: source distribution buster-backports + dpkg-buildpackage: info: source changed by Unit 193 <unit193@debian.org> + dpkg-buildpackage: info: host architecture amd64 + dpkg-source --before-build . + dpkg-source: info: using patch list from debian/patches/series + dpkg-source: info: applying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-source: info: applying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + + ... + + dpkg-genchanges: info: binary-only upload (no source code included) + debian/rules clean + dh clean + dh_clean + dpkg-source --after-build . + dpkg-source: info: unapplying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + dpkg-source: info: unapplying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-buildpackage: info: binary-only upload (no source included) + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Accel-PPP +^^^^^^^^^ + +First, clone the source code and check out the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://github.com/accel-ppp/accel-ppp.git + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ ./build-accel-ppp.sh + I: Build Accel-PPP Debian package + CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy): + The OLD behavior for policy CMP0003 will be removed from a future version + of CMake. + + The cmake-policies(7) manual explains that the OLD behaviors of all + policies are deprecated and that a policy should be set to OLD only under + specific short-term circumstances. Projects should be ported to the NEW + behavior and not rely on setting a policy to OLD. + + -- The C compiler identification is GNU 8.3.0 + + ... + + CPack: Create package using DEB + CPack: Install projects + CPack: - Run preinstall target for: accel-ppp + CPack: - Install project: accel-ppp + CPack: Create package + CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated. + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel NIC +^^^^^^^^^ + +The Intel NIC drivers do not come from a Git repository, instead we just fetch +the tarballs from our mirror and compile them. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + ./build-intel-drivers.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 490k 100 490k 0 0 648k 0 --:--:-- --:--:-- --:--:-- 648k + I: Compile Kernel module for Intel ixgbe driver + + ... + + I: Building Debian package vyos-intel-iavf + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} + I: Cleanup iavf source + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel QAT +^^^^^^^^^ +The Intel QAT (Quick Assist Technology) drivers do not come from a Git +repository, instead we just fetch the tarballs from 01.org, Intel's +open-source website. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + $ ./build-intel-qat.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 5065k 100 5065k 0 0 1157k 0 0:00:04 0:00:04 --:--:-- 1157k + I: Compile Kernel module for Intel qat driver + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for a thread-safe mkdir -p... /bin/mkdir -p + checking for gawk... gawk + checking whether make sets $(MAKE)... yes + + ... + + I: Building Debian package vyos-intel-qat + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"} + I: Cleanup qat source + + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + + Packages ======== @@ -264,7 +627,7 @@ If you are brave enough to build yourself an ISO image containing any modified package from our GitHub organisation - this is the place to be. Any "modified" package may refer to an altered version of e.g. vyos-1x package -that you would like to test before filing a PullRequest on GitHub. +that you would like to test before filing a pull request on GitHub. Building an ISO with any customized package is in no way different then building a regular (customized or not) ISO image. Simply place your modified @@ -275,10 +638,12 @@ Troubleshooting =============== Debian APT is not very verbose when it comes to errors. If your ISO build breaks -for whatever reason and you supect its a problem with APT dependencies or +for whatever reason and you suspect it's a problem with APT dependencies or installation you can add this small patch which increases the APT verbosity during ISO build. +.. stop_vyoslinter + .. code-block:: diff diff --git i/scripts/live-build-config w/scripts/live-build-config @@ -296,6 +661,9 @@ during ISO build. "${@}" """ +.. start_vyoslinter + + Virtualization Platforms ======================== @@ -324,9 +692,9 @@ Run following command after building the QEMU image. Packages ******** -VyOS itself comes with a bunch of packages which are specific to our system and -thus can not be found in any Debian mirrror. Those packages can be found at the -`VyOS GitHub project`_ in their source format can can easily be compiled into +VyOS itself comes with a bunch of packages that are specific to our system and +thus cannot be found in any Debian mirror. Those packages can be found at the +`VyOS GitHub project`_ in their source format can easily be compiled into a custom Debian (`*.deb`) package. The easiest way to compile your package is with the above mentioned @@ -348,7 +716,7 @@ Launch Docker container and build package .. code-block:: none # For VyOS 1.3 (equuleus, current) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash # Change to source directory $ cd vyos-1x @@ -356,8 +724,8 @@ Launch Docker container and build package # Build DEB $ dpkg-buildpackage -uc -us -tc -b -After a minute or two you will find the generated DEB packages next to the vyos-1x -source directory: +After a minute or two you will find the generated DEB packages next to the +vyos-1x source directory: .. code-block:: none @@ -392,8 +760,14 @@ information. the source directories and built deb packages) if you want to build an iso from purely upstream packages. + +.. stop_vyoslinter + .. _Docker: https://www.docker.com .. _`Docker as non-root`: https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user .. _VyOS DockerHub organisation: https://hub.docker.com/u/vyos .. _repository: https://github.com/vyos/vyos-build .. _VyOS GitHub project: https://github.com/vyos + +.. start_vyoslinter + diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 17f5cc48..cf274a33 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -271,7 +271,7 @@ device if you happen to be a crazy scientist. #!/usr/bin/env python3 # - # Copyright (C) 2019 VyOS maintainers and contributors + # Copyright (C) 2020 VyOS maintainers and contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 or later as @@ -291,10 +291,16 @@ device if you happen to be a crazy scientist. from vyos import ConfigError def get_config(): - vc = Config() + if config: + conf = config + else: + conf = Config() + + # Base path to CLI nodes + base = ['...', '...'] # Convert the VyOS config to an abstract internal representation - config = ... - return config + config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) + return config_data def verify(config): # Verify that configuration is valid @@ -311,8 +317,10 @@ device if you happen to be a crazy scientist. pass try: - config = get_config() - verify(config) + c = get_config() + verify(c) + generate(c) + apply(c) except ConfigError as e: print(e) sys.exit(1) @@ -650,8 +658,8 @@ Migrating old CLI validation is better left to commit-time scripts * - priority: 999 - <properties> <priority>999</priority> - - Please leave a comment explaining why the priority was chosen (e.g. "after - interfaces are configured") + - Please leave a comment explaining why the priority was chosen + (e.g. "after interfaces are configured") * - multi: - <properties> <multi/> - Only applicable to leaf nodes @@ -692,6 +700,9 @@ found. After a successful run the resulting Debian Package(s) will be deployed to our Debian repository which is used during build time. It is located here: http://dev.packages.vyos.net/repositories/. + +.. stop_vyoslinter + .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ .. _process: https://blog.vyos.io/vyos-development-digest-10 @@ -703,4 +714,6 @@ http://dev.packages.vyos.net/repositories/. .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt + +.. start_vyoslinter diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 8102e9a9..eb8db3e1 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -1,218 +1,50 @@ -.. _documentation: +.. _contrib-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 -beneficial for you (when reading something up) but also for the whole world. +VyOS documentation is written in reStructuredText and generated to Read the Docs +pages with Sphinx, as per the Python tradition, as well as PDF files for offline +use through LaTeX. -If you are willing to contribute to our documentation this is the definite -guide how to do so. +We welcome all sorts of contributions to the documentation. Not just +new additions but also corrections to existing documentation. -.. note:: In contrast to submitting code patches, there is no requirement that - you open up a Phabricator_ task prior to submitting a Pull-Request to the - documentation. +Guidelines +^^^^^^^^^^ -Forking Workflow ----------------- +There are a few things to keep in mind when contributing to the +documentation, for the sake of consistency and readability. -The Forking Workflow is fundamentally different than other popular Git -workflows. Instead of using a single server-side repository to act as the -"central" codebase, it gives every developer their own server-side repository. -This means that each contributor has not one, but two Git repositories: a -private local one and a public server-side one. +Take a look at the :doc:`/documentation` page for an intricate explanation +of the documentation process. -The main advantage of the Forking Workflow is that contributions can be -integrated without the need for everybody to push to a single central -repository. Developers push to their own server-side repositories, and only the -project maintainer can push to the official repository. This allows the -maintainer to accept commits from any developer without giving them write -access to the official codebase. +The following is a quick summary of the rules: -.. note:: Updates to our documentation should be delivered by a GitHub - pull-request. This requires you already have a GitHub account. +- Use American English at all times. It's always a good idea to run + your text through a grammar and spell checker, such as `Grammarly`_. +- Don't forget to update ``index.rst`` when adding a new node. +- Try not to exceed 80 characters per line, but don't break URLs over this. +- Properly quote commands, filenames and brief code snippets with double backticks. +- Use literal blocks for longer snippets. +- Leave a newline before and after a header. +- Indent with two spaces. +- When in doubt, follow the style of existing documentation. -* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork +And finally, remember that the reStructuredText files aren't +exclusively for generating HTML and PDF. They should be human-readable +and easily perused from a console. -* Clone fork to local machine - -* Change to your new local directory ``$ cd vyos-documentation`` - -* Create new branch for your work, use a descriptive name of your work: - ``$ git checkout -b fix-vxlan-typo`` - -* Make all your changes - please keep our commit rules in mind - (:ref:`prepare_commit`). This mainly applies to proper commit messages - describing your change (how and why). Please check out the documentation of - Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used - for writing our docs. - -* Check your changes by locally building the documentation ``$ make html``. - Sphinx will build the html files in the ``docs/_build`` folder. We provide - you with a Docker container for an easy to use user experience. Check the - README.md_ file of this repository. - -* View modified files by calling ``$ git status``. You will get an overview of - all files modified by you. You can add individual files to the Git Index in - the next step. - -* Add modified files to Git index ``$ git add path/to/filename`` or add all - unstaged files ``$ git add .``. All files added to the Git index will be part - of you following Git commit. - -* Commit your changes ``$ git commit -v`` - your configured editor will now ne - launched where you can type in a commit message. Again please make yourself - comfortable with out rules (:ref:`prepare_commit`). - -* Push your commits to your GitHub project: ``$ git push -u origin foo-branch`` - -* Submit pull-request. In GitHub visit the main repository and you should - see a banner suggesting to make a pull request. Fill out the form and - describe what you do. - -* Once pull resquests have been approved, you may want to locally update - your forked repository too. First you'll have to add a second remote - called `upstream` which points to our main repository. ``$ git remote add - upstream https://github.com/vyos/vyos-documentation.git`` - - Check your configured remote repositories: - - .. code-block:: none - - $ git remote -v - origin https://github.com/<username>/vyos-documentation.git (fetch) - origin https://github.com/<username>/vyos.documentation.git (push) - upstream https://github.com/vyos/vyos-documentation.git (fetch) - upstream https://github.com/vyos/vyos-documentation.git (push) - - Your remote repo on Github is called ``origin``, while the original repo you - have forked is called ``upstream``. Now you can locally update your forked - repo. - - .. code-block:: none - - $ git fetch upstream - $ git checkout master - $ git merge upstream/master - -* If you want to update your fork on GitHub, too use the following: ``$ git - push origin master`` - -Style Guide ------------ - -Sections +Building ^^^^^^^^ -We use the following syntax for Headlines. - -.. code-block:: none - - ##### - Parts - ##### - - ******** - Chapters - ******** - - Sections - ======== - - Subsections - ----------- - - Subsubsections - ^^^^^^^^^^^^^^ - - Paragraphs - """""""""" - -Address space -^^^^^^^^^^^^^ - -Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and -:rfc:`7042`), which describe the reserved public IP addresses and autonomous -system numbers for the documentation: - - * ``192.0.2.0/24`` - * ``198.51.100.0/24`` - * ``203.0.113.0/24`` - * ``2001:db8::/32`` - * 16bit ASN: ``64496 - 64511`` - * 32bit ASN: ``65536 - 65551`` - * Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF`` - * Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF`` - -Please don't use other public address space. - -Custom Sphinx-doc Markup -^^^^^^^^^^^^^^^^^^^^^^^^ - -When writing the documentation custom commands have been developed. Please -make yourself comfortable with those commands as this eases the way we -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. - -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 - - This will configure a static ARP entry always resolving `192.0.2.100` to - `00:53:27:de:23:aa`. - -For a inline configuration level command use ``:cfgcmd:`` - -.. code-block:: none - - :cfgcmd:`set interface ethernet eth0` - -opcmd -""""" - -When documenting operational level command use the ``.. opcmd::`` directive. -An explanation of the described command should be added below this statement. - -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 - - .. opcmd:: show protocols static arp - - Display all known ARP table entries spanning across all interfaces - -For a inline operational level command use ``:opcmd:`` - -.. code-block:: none - - :opcmd:`add system image` - -vytask -"""""" - -When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup -command called ``vytask`` which automatically renders to a proper Phabricator -URL. This is heavily used in the :ref:`release-notes` section. - -.. code-block:: none - - * :vytask:`T1605` Fixed regression in L2TP/IPsec server - * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +The source is kept in the Git repository +https://github.com/vyos/vyos-documentation +You can follow the instructions in the README to build and test your changes. -.. _Sphinx-doc: https://www.sphinx-doc.org -.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md +You can either install Sphinx (and TeX Live for PDF output) and build the +documentation locally, or use the `Dockerfile`_ to build it in a container. -.. include:: ../common-references.rst +.. _Dockerfile: https://github.com/vyos/vyos-documentation/blob/master/docker/Dockerfile +.. _Grammarly: https://www.grammarly.com/ diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..481c6da8 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,12 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 2 + + build-vyos + development + documentation + issues-features + upstream-packages diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 60e49974..9b6602f9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -77,4 +77,4 @@ the left side under the specific project. .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. include:: ../common-references.rst +.. include:: /_include/common-references.txt diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index d43e61f3..5c48bbb3 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -59,26 +59,6 @@ reason we debianize that module by hand now, using this procedure: The package ends up in deb_dist dir. -ppp -^^^ - -Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and -non-informative pppX requires a patch that is neither in the upstream nor in -Debian. - -We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian - -The patches for pre-up renaming are: - -* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae -* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9 - -Additionally, there's a patch for reopening the log file to better support -logging to files, even though it's less essential: -https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f - -The patches were written by Stephen Hemminger back in the Vyatta times. - mdns-repeater ^^^^^^^^^^^^^ @@ -95,58 +75,6 @@ https://github.com/vyos/udp-broadcast-relay No special build procedure is required. -Linux kernel -^^^^^^^^^^^^ - -In the past a fork of the Kernel source code was kept at the well-known -location of https://github.com/vyos/vyos-kernel - where it is kept for history. - -Nowadays the Kernel we use is the upstream source code which is patched -with two additional patches from the good old Vyatta times which never made it -into the mainstream Kernel. The patches can be found here: -https://github.com/vyos/vyos-build-kernel/tree/master/patches/kernel and are -automatically applied to the Kernel by the Jenkins Pipeline which is used to -generate the Kernel binaries. - -The Pipeline script not only builds the Kernel with the configuration named -``x86_64_vyos_defconfig`` which is located in the vyos-build-kernel repository, -too - but in addition also builds some Intel out-of-tree drivers, WireGuard -(as long it is not upstreamed) and Accel-PPP. - -The ``Jenkinsfile`` tries to be as verbose as possible on each individual build -step. - -Linux Firmware -^^^^^^^^^^^^^^ - -More and more hardware cards require an additional firmware which is not open -source. The Kernel community hosts a special linux-firmware Git repository -with all available binary files which can be loaded by the Kernel. - -The ``vyos-build`` repository fetches a specific commit of the linux-firmware -repository and embeds those binaries into the resulting ISO image. This step is -done in the ``data/live-build-config/hooks/live/40-linux-firmware.chroot`` file. - -If the firmware needs to be updated it is sufficient to just exchange the Git -commit id we reference in our build. - -Intel NIC drivers -^^^^^^^^^^^^^^^^^ - -We do not make use of the building Intel NIC drivers except for e1000e. Main -reason is that the out of tree Intel drivers seem be perform a bit better, -e.q. have proper receive-side-scaling and multi-queue support. - -Drivers are build as part of the Kernel Pipeline - read above. - -Accel-PPP -^^^^^^^^^ - -Accel-PPP used to be an upstream fork for quite some time but now has been -converted to make use of the upstream source code and build system. - -It is build as part of the Kernel Pipeline - read above. - hvinfo ^^^^^^ 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/coverage.rst b/docs/coverage.rst new file mode 100644 index 00000000..180dfe4b --- /dev/null +++ b/docs/coverage.rst @@ -0,0 +1,49 @@ +######## +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 <https://github.com/vyos/vyos-1x>`_ and extract each leaf +command or executable command. After this the commands are compare and shown in +the following 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 <interface> address + <address | dhcp | dhcpv6>``` + * xml: ``interface ethernet <ethernet> address <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 diff --git a/docs/contributing/debugging.rst b/docs/debugging.rst index ac2e0510..6150ff60 100644 --- a/docs/contributing/debugging.rst +++ b/docs/debugging.rst @@ -29,7 +29,8 @@ Kernel CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug`` will ensure access to the system as user ``vyos``, and will log a Python stack trace to the file ``/tmp/boot-config-trace``. - File ``boot-config-trace`` will generate only if config loaded with a failure status. + File ``boot-config-trace`` will generate only if config loaded with a failure + status. Live System =========== @@ -51,7 +52,7 @@ interface debugging. It is also possible to set up the debugging using environment variables. In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. -For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vash, +For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash, will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. * ``ifconfig`` - Once set, all commands used, and their responses received @@ -71,6 +72,47 @@ will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. including during boot. This option sends all commands used by VyOS to a file. The default file is ``/tmp/full-log`` but it can be changed. +.. note:: In order to retrieve the debug output on the command-line you need to + disable ``vyos-configd`` in addition. This can be run either one-time by + calling ``sudo systemctl stop vyos-configd`` or make this reboot-safe by + calling ``sudo systemctl disable vyos-configd``. + +Debugging Python Code with PDB +------------------------------ + +Sometimes it might be useful to debug Python code interactively on the live +system rather than a IDE. This can be achieved using pdb. + +Let us assume you want to debug a Python script that is called by an op-mode +command. After you found the script by looking up the op-mode-defitions you +can edit the script in the live system using e.g. vi: +``vi /usr/libexec/vyos/op_mode/show_xyz.py`` + +Insert the following statement right before the section where you want to +investigate a problem (e.g. a statement you see in a backtrace): +``import pdb; pdb.set_trace()`` +Optionally you can surrounded this statement by an ``if`` which only triggers +under the condition you are interested in. + +Once you run ``show xyz`` and your condition is triggered you should be dropped +into the python debugger: + + +.. code-block:: none + + > /usr/libexec/vyos/op_mode/show_nat_translations.py(109)process() + -> rule_type = rule.get('type', '') + (Pdb) + +You can type ``help`` to get an overview of the available commands, and +``help command`` to get more information on each command. + +Useful commands are: + +* examine variables using ``pp(var)`` +* contine execution using ``cont`` +* get a backtrace using ``bt`` + Config Migration Scripts ------------------------ @@ -130,17 +172,20 @@ This can also be done permanently by changing ``/boot/grub/grub.cfg``. Priorities ========== -VyOS CLI is all about priorities. Every CLI node has a corresponding ``node.def`` -file and possibly an attached script that is executed when the node is present. -Nodes can have a priority, and on system bootup - or any other ``commit`` to the -config all scripts are executed from lowest to higest priority. This is good as -this gives a deterministic behavior. +VyOS CLI is all about priorities. Every CLI node has a corresponding +``node.def`` file and possibly an attached script that is executed when the +node is present. Nodes can have a priority, and on system bootup - or any +other ``commit`` to the config all scripts are executed from lowest to higest +priority. This is good as this gives a deterministic behavior. + +To debug issues in priorities or to see what's going on in the background +you can use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you +the execution order of the scripts. -To debug issues in priorities or to see what's going on in the background you can -use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you the execution -order of the scripts. +.. stop_vyoslinter .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg .. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf +.. include:: /_include/common-references.txt -.. include:: ../common-references.rst +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/documentation.rst b/docs/documentation.rst new file mode 100644 index 00000000..849008a8 --- /dev/null +++ b/docs/documentation.rst @@ -0,0 +1,347 @@ +.. _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 +beneficial for you (when reading something up) but also for the whole world. + +If you are willing to contribute to our documentation this is the definite +guide how to do so. + +.. note:: In contrast to submitting code patches, there is no requirement that + you open up a Phabricator_ task prior to submitting a Pull-Request to the + 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 +"central" codebase, it gives every developer their own server-side repository. +This means that each contributor has not one, but two Git repositories: a +private local one and a public server-side one. + +The main advantage of the Forking Workflow is that contributions can be +integrated without the need for everybody to push to a single central +repository. Developers push to their own server-side repositories, and only the +project maintainer can push to the official repository. This allows the +maintainer to accept commits from any developer without giving them write +access to the official codebase. + +.. note:: Updates to our documentation should be delivered by a GitHub + pull-request. This requires you already have a GitHub account. + +* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork + +* Clone fork to local machine, then change to that directory + ``$ cd vyos-documentation`` + +* Install the requirements ``$ pip install -r requirements.txt`` + (or something similar) + +* Create new branch for your work, use a descriptive name of your work: + ``$ git checkout -b <branch-name>`` + +* Make all your changes - please keep our commit rules in mind + (:ref:`prepare_commit`). This mainly applies to proper commit messages + describing your change (how and why). Please check out the documentation of + Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used + for writing our docs. Additional directives how to write in RST can be + obtained from reStructuredTextDirectives_. + +* Check your changes by locally building the documentation ``$ make html``. + Sphinx will build the html files in the ``docs/_build`` folder. We provide + you with a Docker container for an easy to use user experience. Check the + README.md_ file of this repository. + +* View modified files by calling ``$ git status``. You will get an overview of + all files modified by you. You can add individual files to the Git Index in + the next step. + +* Add modified files to Git index ``$ git add path/to/filename`` or add all + unstaged files ``$ git add .``. All files added to the Git index will be part + of you following Git commit. + +* Commit your changes with the message, ``$ git commit -m "<commit message>"`` + or use ``$ git commit -v`` to have your configured editor launched. You can + type in a commit message. Again please make yourself comfortable with out + rules (:ref:`prepare_commit`). + +* Push commits to your GitHub project: ``$ git push -u origin <branch-name>`` + +* Submit pull-request. In GitHub visit the main repository and you should + see a banner suggesting to make a pull request. Fill out the form and + describe what you do. + +* Once pull resquests have been approved, you may want to locally update + your forked repository too. First you'll have to add a second remote + called `upstream` which points to our main repository. ``$ git remote add + upstream https://github.com/vyos/vyos-documentation.git`` + + Check your configured remote repositories: + + .. code-block:: none + + $ git remote -v + origin https://github.com/<username>/vyos-documentation.git (fetch) + origin https://github.com/<username>/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + + Your remote repo on Github is called ``origin``, while the original repo you + have forked is called ``upstream``. Now you can locally update your forked + repo. + + .. code-block:: none + + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + +* If you want to update your fork on GitHub, too use the following: ``$ git + push origin master`` + +Style Guide +=========== + +Formating and Sphinxmarkup +-------------------------- + +TOC Level +^^^^^^^^^^ + +We use the following syntax for Headlines. + +.. code-block:: none + + ##### + Title + ##### + + ******** + Chapters + ******** + + Sections + ======== + + Subsections + ----------- + + Subsubsections + ^^^^^^^^^^^^^^ + + Paragraphs + """""""""" + +Address space +^^^^^^^^^^^^^ + +Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and +:rfc:`7042`), which describe the reserved public IP addresses and autonomous +system numbers for the documentation: + + * ``192.0.2.0/24`` + * ``198.51.100.0/24`` + * ``203.0.113.0/24`` + * ``2001:db8::/32`` + * 16bit ASN: ``64496 - 64511`` + * 32bit ASN: ``65536 - 65551`` + * Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF`` + * Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF`` + +Please don't use other public address space. + + +Line length +^^^^^^^^^^^ + +Limit all lines to a maximum of 80 characters. + +Except in ``.. code-block::`` because it will use the html tag ``<pre>`` +which have the save line format as in the rst file. + + +Autolinter +^^^^^^^^^^ + +Each GitHub Pull request will automatically lint against the Address space and +line length. + +Sometimes it is necessary to provide real IP Addresses like in the +:ref:`examples`. For this please use the sphinx comment syntax +``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start. + + +Custom Sphinx-doc Markup +^^^^^^^^^^^^^^^^^^^^^^^^ + +When writing the documentation custom commands have been developed. Please +make yourself comfortable with those commands as this eases the way we +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. +Replace all variable contents with <value> 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:: protocols static arp <ipaddress> hwaddr <macaddress> + + This will configure a static ARP entry always resolving `192.0.2.100` to + `00:53:27:de:23:aa`. + +For a inline configuration level command use ``:cfgcmd:`` + +.. code-block:: none + + :cfgcmd:`set interface ethernet eth0` + +opcmd +""""" + +When documenting operational level command use the ``.. opcmd::`` directive. +An explanation of the described command should be added below this statement. + +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 + + .. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +For a inline operational level command use ``:opcmd:`` + +.. code-block:: none + + :opcmd:`add system image` + +cmdinclude +"""""""""" + +To minimize redundancy there is a special include directive. It include a txt +file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value + +.. code-block:: none + + .. cmdinclude:: /_include/interface-address.txt + :var0: ethernet + :var1: eth1 + +the content of interface-address.txt looks like this + +.. code-block:: none + + .. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 + +vytask +"""""" + +When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup +command called ``vytask`` which automatically renders to a proper Phabricator +URL. This is heavily used in the :ref:`release-notes` section. + +.. code-block:: none + + * :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. + +All RST files must follow the same TOC Level syntax and have to start with + +.. code-block:: + + ##### + Titel + ##### + +Configuration mode pages +^^^^^^^^^^^^^^^^^^^^^^^^ + +A configuration mode folder and article covers a specific level of a command. +The exact level depends on the command. This should provide stability for URLs +used in the forum or blogpost. + +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. Please 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 article. +Use ``::opcmd..`` for these commands. + +If there some troubleshooting guides releated to the commands. Explain it in the +next optional part. + +Operation mode pages +^^^^^^^^^^^^^^^^^^^^ + +Operation mode commands, which didn't fit in a related configuraton mode command +must documented in this part of the documentation. + +General concepts for troubleshooting belong here as well as detailed process +descriptions. + +Anything else +^^^^^^^^^^^^^ + +Anything else what is not a configuration or a operation command have no +predefined structure. + + +.. stop_vyoslinter + +.. _Sphinx-doc: https://www.sphinx-doc.org +.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html +.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md +.. include:: /_include/common-references.txt + +.. start_vyoslinter diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst deleted file mode 100644 index 6c1b2587..00000000 --- a/docs/image-mgmt.rst +++ /dev/null @@ -1,181 +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:`set system image default-boot`). - -.. 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:: set system image default-boot - - Select the default boot image which will be started on the next boot of the - System. A list of available images can be shown using the :opcmd:`show - system image` - - -.. 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 <url | path> [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. - - - - diff --git a/docs/index.rst b/docs/index.rst index bab4f930..574a2c49 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,106 +4,43 @@ VyOS User Guide ############### - -.. toctree:: - :caption: Introduction - :name: intro - :maxdepth: 2 - - about - history - install - cli - quick-start - - .. toctree:: - :caption: Basic Configuration - :name: basics - :maxdepth: 2 + :maxdepth: 1 - configuration-overview - interfaces/basic-index - system/basic-index - image-mgmt + introducing/about + introducing/history + changelog/index .. toctree:: - :caption: Advanced Configuration - :name: advanced :maxdepth: 2 + :includehidden: + :caption: First Steps - 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 + :includehidden: + :caption: Adminguide - information - troubleshooting - command-list-operation - - -.. toctree:: - :caption: Appendix - :name: appendix - :maxdepth: 2 - appendix/release-notes - appendix/examples/index - appendix/vyos-on-vmware - appendix/vyos-on-baremetal - appendix/vyos-on-clouds - appendix/vyos-on-virtual-environments - appendix/migrate-from-vyatta - appendix/command-scripting - appendix/http-api - appendix/vyos-on-gns3 + configuration/index + operation/index + automation/index + troubleshooting/index + configexamples/index .. toctree:: - :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. + :includehidden: + :caption: Development + + contributing/index + debugging + documentation + coverage + copyright diff --git a/docs/installation/cloud/aws.rst b/docs/installation/cloud/aws.rst new file mode 100644 index 00000000..d64aca82 --- /dev/null +++ b/docs/installation/cloud/aws.rst @@ -0,0 +1,57 @@ +########## +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..e19df986 --- /dev/null +++ b/docs/installation/cloud/azure.rst @@ -0,0 +1,72 @@ +##### +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`` and choose the appropriate subscription + +.. 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 a few seconds 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. + +Absorbing Routes +---------------- + +If using as a router, you will want your LAN interface to absorb some or all of the traffic from your VNET by using a route table applied to the subnet. + +1. Create a route table and browse to **Configuration** + +2. Add one or more routes for networks you want to pass through the VyOS VM. Next hop type **Virtual Appliance** with the **Next Hop Address** of the VyOS ``LAN`` interface. + +.. note:: If you want to create a new default route for VMs on the subnet, use **Address Prefix** ``0.0.0.0/0`` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the ``WAN`` interface. + +Serial Console +-------------- + +Azure has a way to access the serial console of a VM, but this needs to be configured on the VyOS. It's there by default, but keep it in mind if you are replacing config.boot and rebooting: ``set system console device ttyS0 speed '9600'`` + +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..07aecdbe --- /dev/null +++ b/docs/installation/cloud/gcp.rst @@ -0,0 +1,58 @@ +##################### +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 new file mode 100644 index 00000000..435a16cd --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,17 @@ +################################# +Installation and Image Management +################################# + + + +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + virtual/index + cloud/index + vyos-on-baremetal + update + image + migrate-from-vyatta diff --git a/docs/install.rst b/docs/installation/install.rst index 26d7c7c8..b5472f64 100644 --- a/docs/install.rst +++ b/docs/installation/install.rst @@ -190,7 +190,7 @@ 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. +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 @@ -206,8 +206,8 @@ stick with with the ``dd`` command: all partitions. .. code-block:: none - - $ umount /dev/sdX* + + $ 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 @@ -216,13 +216,13 @@ stick with with the ``dd`` command: **Warning**: This will destroy all data on the USB drive! .. code-block:: none - - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M + + # 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, plug the USB drive out and plug it into + 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 @@ -239,7 +239,7 @@ 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``. +.. hint:: The default username and password for the live system is *vyos*. .. _permanent_installation: @@ -247,7 +247,8 @@ file. Permanent installation ====================== -.. note:: Before a permanent installation, VyOS requires a :ref:`live_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 @@ -286,19 +287,19 @@ In order to proceed with a permanent installation: 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... @@ -310,7 +311,7 @@ In order to proceed with a permanent installation: 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': @@ -318,9 +319,9 @@ In order to proceed with a permanent installation: 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! @@ -351,19 +352,20 @@ installation method which allows deploying VyOS through the network. * :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 <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution + <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ 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`` +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* In this example we configured an existent VyOS as the DHCP server: @@ -385,24 +387,22 @@ In this example we configured an existent VyOS as the DHCP server: .. _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 *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 + *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_. In the example we configured our existent VyOS as the TFTP server too: @@ -444,37 +444,46 @@ Example of simple (no menu) configuration file: APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs Step 3: HTTP -"""""""""""" +^^^^^^^^^^^^ -As you can read in the configuration file, we are sending ``filesystem.squashfs`` -through HTTP. As that is a heavy file, we choose HTTP to speed up the transfer -over TFTP. +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. +**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 at the :ref:`install_from_tftp` so that it shows -the correct URL at ``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. -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:: 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. -.. 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. +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. +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. @@ -484,21 +493,31 @@ 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. +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: +The workaround is to type `e` when the boot menu appears and edit the GRUB boot +options. Specifically, remove the: -`console=ttyS0,115200` +`console=ttyS0,115200` -option, and type CTRL-X to boot. +option, and type CTRL-X to boot. Installation can then continue as outlined above. + +.. stop_vyoslinter + .. _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 +.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config +.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration +.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst index f15c3d5a..f15c3d5a 100644 --- a/docs/appendix/migrate-from-vyatta.rst +++ b/docs/installation/migrate-from-vyatta.rst diff --git a/docs/installation/update.rst b/docs/installation/update.rst new file mode 100644 index 00000000..5bcd5b8a --- /dev/null +++ b/docs/installation/update.rst @@ -0,0 +1,82 @@ +.. _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 <url | path> [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/appendix/vyos-on-gns3.rst b/docs/installation/virtual/gns3.rst index f17715b2..e9977f0f 100644 --- a/docs/appendix/vyos-on-gns3.rst +++ b/docs/installation/virtual/gns3.rst @@ -1,7 +1,8 @@ .. _vyos-on-gns3: -VyOS on GNS3 -############ +############### +Running on GNS3 +############### Sometimes you may want to test VyOS in a lab environment. `GNS3 <http://www.gns3.com>`__ is a network emulation software you @@ -15,9 +16,8 @@ Requirements The following items are required: -* A VyOS installation image (.iso file). - `Here <https://docs.vyos.io/en/latest/install.html#download>`__ you - can find how to get it. +* A VyOS installation image (.iso file). You + can find how to get it on the :ref:`installation` page * A working GNS3 installation. For further information see the `GNS3 documentation <https://docs.gns3.com/>`__. 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/appendix/vyos-on-virtual-environments.rst b/docs/installation/virtual/libvirt.rst index eed82390..ff896d07 100644 --- a/docs/appendix/vyos-on-virtual-environments.rst +++ b/docs/installation/virtual/libvirt.rst @@ -1,16 +1,13 @@ -.. _vyos-on-virtual-environments: +.. _libvirt: -############################### -Running in Virtual Environments -############################### +*************************** +Running on Libvirt Qemu/KVM +*************************** -**************** -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. +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 === @@ -18,8 +15,9 @@ 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. +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 @@ -50,11 +48,13 @@ Connect to VM with command ``virsh console vyos_r1`` vyos@vyos:~$ install image -After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. +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. +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 @@ -96,13 +96,15 @@ 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)`. +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)` +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new + :abbr:`VM (Virtual Machine)` 2. Choose ``Local install media`` (ISO) @@ -138,13 +140,15 @@ Download predefined VyOS.qcow2 image for ``KVM`` 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)` +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. +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 @@ -161,12 +165,4 @@ Download predefined VyOS.qcow2 image for ``KVM`` .. figure:: /_static/images/virt-libvirt-qc-03.png -******* -Proxmox -******* - -References -========== - -https://www.proxmox.com/en/proxmox-ve 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..28614573 --- /dev/null +++ b/docs/installation/virtual/vmware.rst @@ -0,0 +1,46 @@ +.. _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
+----------
+
+.. stop_vyoslinter
+
+https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html
+
+.. start_vyoslinter
\ No newline at end of file diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst index db618431..81d04f0d 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/installation/vyos-on-baremetal.rst @@ -109,8 +109,8 @@ Extension Modules WiFi """" -Refer to :ref:`wireless-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform: +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. @@ -118,7 +118,8 @@ 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): +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) @@ -137,6 +138,7 @@ 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. +.. stop_vyoslinter .. code-block:: none PC Engines apu4 @@ -154,6 +156,9 @@ Set terminal emulator to 115200 8N1. 3. Payload [memtest] 4. Payload [setup] +.. start_vyoslinter + + 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. diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst deleted file mode 100644 index 425792a2..00000000 --- a/docs/interfaces/basic-index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _basic_network-interfaces: - -######################## -Basic Network Interfaces -######################## - -.. toctree:: - :maxdepth: 1 - - ethernet - loopback - pppoe diff --git a/docs/interfaces/common-ip-ipv6-addr.txt b/docs/interfaces/common-ip-ipv6-addr.txt deleted file mode 100644 index f53eaeee..00000000 --- a/docs/interfaces/common-ip-ipv6-addr.txt +++ /dev/null @@ -1,8 +0,0 @@ -Configure interface `<interface>` with one or more interface addresses. - -* **address** can be specified multiple times as IPv4 and/or IPv6 address, - e.g. 192.0.2.1/24 and/or 2001:db8::1/64 -* **dhcp** interface address is received by DHCP from a DHCP server on this - segment. -* **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on - this segment. diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt deleted file mode 100644 index 838b299f..00000000 --- a/docs/interfaces/common-ipv6-addr-autoconf.txt +++ /dev/null @@ -1,12 +0,0 @@ -:abbr:`SLAAC (Stateless Address Autoconfiguration)`
-:rfc:`4862`. IPv6 hosts can configure themselves automatically when connected
-to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6
-(Internet Control Message Protocol version 6)` router discovery messages.
-When first connected to a network, a host sends a link-local router
-solicitation multicast request for its configuration parameters; routers
-respond to such a request with a router advertisement packet that contains
-Internet Layer configuration parameters.
-
-.. note:: This method automatically disables IPv6 traffic forwarding on the
- interface in question.
-
diff --git a/docs/interfaces/qinq.rst b/docs/interfaces/qinq.rst deleted file mode 100644 index 01d9c64a..00000000 --- a/docs/interfaces/qinq.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _qinq-interface: - -QinQ (802.1ad) --------------- - -IEEE 802.1ad was an Ethernet networking standard informally known as QinQ as -an amendment to IEEE standard :ref:`vlan-interface`. 802.1ad was incorporated -into the base 802.1q standard in 2011. The technique is also known as provider -bridging, Stacked VLANs, or simply QinQ or Q-in-Q. "Q-in-Q" can for supported -devices apply to C-tag stacking on C-tag (Ethernet Type = 0x8100). - -The original 802.1q specification allows a single Virtual Local Area Network -(VLAN) header to be inserted into an Ethernet frame. QinQ allows multiple -VLAN tags to be inserted into a single frame, an essential capability for -implementing Metro Ethernet network topologies. Just as QinQ extends 802.1Q, -QinQ itself is extended by other Metro Ethernet protocols. - -In a multiple VLAN header context, out of convenience the term "VLAN tag" or -just "tag" for short is often used in place of "802.1Q VLAN header". QinQ -allows multiple VLAN tags in an Ethernet frame; together these tags constitute -a tag stack. When used in the context of an Ethernet frame, a QinQ frame is a -frame that has 2 VLAN 802.1Q headers (double-tagged). - -In VyOS the terms **vif-s** and **vif-c** stand for the ethertype tags that -are used: - -The inner tag is the tag which is closest to the payload portion of the frame. -It is officially called C-TAG (customer tag, with ethertype 0x8100). The outer -tag is the one closer/closest to the Ethernet header, its name is S-TAG -(service tag with ethertype 0x88a8). - -Configuration commands: - -.. code-block:: none - - interfaces - ethernet <eth[0-999]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-s <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-c <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - - -Example: - -.. code-block:: none - - set interfaces ethernet eth0 vif-s 333 - set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 - set interfaces ethernet eth0 vif-s 333 vif-c 777 - set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 - -.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad
\ No newline at end of file diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst deleted file mode 100644 index 55656d5d..00000000 --- a/docs/interfaces/vlan.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _vlan-interface: - -VLAN (802.1q) -------------- - -IEEE 802.1q, often referred to as Dot1q, is the networking standard that -supports virtual LANs (VLANs) on an IEEE 802.3 Ethernet network. The -standard defines a system of VLAN tagging for Ethernet frames and the -accompanying procedures to be used by bridges and switches in handling -such frames. The standard also contains provisions for a quality-of-service -prioritization scheme commonly known as IEEE 802.1p and defines the Generic -Attribute Registration Protocol. - -Portions of the network which are VLAN-aware (i.e., IEEE 802.1q conformant) -can include VLAN tags. When a frame enters the VLAN-aware portion of the -network, a tag is added to represent the VLAN membership. Each frame must -be distinguishable as being within exactly one VLAN. A frame in the -VLAN-aware portion of the network that does not contain a VLAN tag is -assumed to be flowing on the native VLAN. - -The standard was developed by IEEE 802.1, a working group of the IEEE 802 -standards committee, and continues to be actively revised. One of the -notable revisions is 802.1Q-2014 which incorporated IEEE 802.1aq (Shortest -Path Bridging) and much of the IEEE 802.1d standard. - -802.1a VLAN interfaces are represented as virtual sub-interfaces in VyOS. The -term used for this is ``vif``. Configuration of a tagged sub-interface is -accomplished using the configuration command: -``set interfaces ethernet <name> vif <vlan-id>`` - -To assign a vif 100 using the VLAN 100 tag to physical interface eth1 use: - -.. code-block:: none - - set interfaces ethernet eth1 vif 100 description 'VLAN 100' - set interfaces ethernet eth1 vif 100 address '192.168.100.1/24' - set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - description INSIDE - duplex auto - hw-id 00:53:29:44:3b:19 - smp_affinity auto - speed auto - vif 100 { - address 192.168.100.1/24 - description "VLAN 100" - } - } - -VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.16.51.129/24 u/u OUTSIDE - eth1 192.168.0.1/24 u/u INSIDE - eth1.100 192.168.100.1/24 u/u VLAN 100 - lo 127.0.0.1/8 u/u - ::1/128 diff --git a/docs/about.rst b/docs/introducing/about.rst index 0411344b..0411344b 100644 --- a/docs/about.rst +++ b/docs/introducing/about.rst diff --git a/docs/history.rst b/docs/introducing/history.rst index 9a13e2b3..9a13e2b3 100644 --- a/docs/history.rst +++ b/docs/introducing/history.rst diff --git a/docs/nptv6.rst b/docs/nptv6.rst deleted file mode 100644 index dc725a03..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 outside-interface 'eth1' - set rule 10 translation prefix '2001:db8:e1::/48' - set rule 20 source prefix 'fc00:dead:beef::/48' - set rule 20 outside-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/operation/boot-options.rst b/docs/operation/boot-options.rst new file mode 100644 index 00000000..70cdc418 --- /dev/null +++ b/docs/operation/boot-options.rst @@ -0,0 +1,58 @@ +.. _boot-options: + + +############ +Boot Options +############ + +.. warning:: This function may be highly disruptive. + It may cause major service interruption, so make sure you really + need it and verify your input carefully. + + + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +.. image:: /_static/images/boot-options.png + :width: 80% + :align: center + + +Specify custom config file +========================== + +Tells the system to use specified file instead of ``/config/config.boot``. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +.. code-block:: none + + vyos-config=/path/to/file + +To load the *factory default* config, use: + +.. code-block:: none + + vyos-config=/opt/vyatta/etc/config.boot.default + + +Disable specific boot process steps +=================================== + +These options disable some boot steps. Make sure you understand the +:ref:`boot process <boot-steps>` well before using them! + +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall + configuration unusable. + diff --git a/docs/operation/index.rst b/docs/operation/index.rst new file mode 100644 index 00000000..c19afeab --- /dev/null +++ b/docs/operation/index.rst @@ -0,0 +1,10 @@ +############## +Operation Mode +############## + +.. toctree:: + :maxdepth: 1 + :includehidden: + + information + boot-options
\ No newline at end of file diff --git a/docs/information.rst b/docs/operation/information.rst index 5565163e..ec2506cb 100644 --- a/docs/information.rst +++ b/docs/operation/information.rst @@ -5,7 +5,7 @@ Information *********** VyOS features a rich set of operational level commands to retrieve arbitrary -infomration about your running system. +information about your running system. ######## Hardware @@ -19,15 +19,15 @@ USB In the past serial interface have been defined as ttySx and ttyUSBx where x was an instance number of the serial interface. It was discovered that from system boot to system boot the mapping of USB based serial interfaces will differ, -depending which driver was loaded first by the operating system. This will become -rather painful if you not only have serial interfaces for a console server -connected but in addition also a serial backed :ref:`wwan-interface`. +depending which driver was loaded first by the operating system. This will +become rather painful if you not only have serial interfaces for a console +server connected but in addition also a serial backed :ref:`wwan-interface`. -To overcome this issue and the fact that in almost 50% of all cheap USB to serial -converters there is no serial number programmed, the USB to serial interface is -now directly identified by the USB root bridge and bus it connects to. This -somehow mimics the new network interface definitions we see in recend Linux -distributions. +To overcome this issue and the fact that in almost 50% of all cheap USB to +serial converters there is no serial number programmed, the USB to serial +interface is now directly identified by the USB root bridge and bus it connects +to. This somehow mimics the new network interface definitions we see in recend +Linux distributions. For additional details you can refer to https://phabricator.vyos.net/T2490. @@ -69,9 +69,9 @@ For additional details you can refer to https://phabricator.vyos.net/T2490. .. opcmd:: show hardware usb serial - Retrieve a list and description of all connected USB serial devices. The device name - displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing the serial console - as console-server device. + Retrieve a list and description of all connected USB serial devices. The + device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing + the serial console as console-server device. .. code-block:: none @@ -94,4 +94,3 @@ For additional details you can refer to https://phabricator.vyos.net/T2490. usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 19ee9f6e..655ce072 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -4,16 +4,20 @@ Quick Start ########### -This chapter will guide you on how to get up to speed using your new VyOS -system. It will show you a very basic configuration example that will provide -a :ref:`nat` gateway for a device with two network interfaces (`eth0` and -`eth1`). +This chapter will guide you on how to get up to speed quickly using your new +VyOS system. It will show you a very basic configuration example that will +provide a :ref:`nat` gateway for a device with two network interfaces +(`eth0` and `eth1`). .. _quick-start-configuration-mode: Configuration Mode ################## +By default, VyOS is in operational mode, and the command prompt displays a `$`. +To configure VyOS, you will need to enter configuration mode, resulting in the +command prompt displaying a `#`, as demonstrated below: + .. code-block:: none vyos@vyos$ configure @@ -22,13 +26,15 @@ Configuration Mode Commit and Save ################ -After every configuration change you need to apply the changes by using the +After every configuration change, you need to apply the changes by using the +following command: .. code-block:: none commit -Once your configuration works as expected you can save it permanently. +Once your configuration works as expected, you can save it permanently by using +the following command: .. code-block:: none @@ -37,10 +43,10 @@ Once your configuration works as expected you can save it permanently. Interface Configuration ####################### -* Your outside/WAN interface will be `eth0`, it receives it's interface address - be means of DHCP. -* Your internal/LAN interface is `eth1`. It uses a fixed IP address of - `192.168.0.1/24`. +* Your outside/WAN interface will be `eth0`. It will receive its interface + address via DHCP. +* Your internal/LAN interface will be `eth1`. It will use a static IP address + of `192.168.0.1/24`. After switching to :ref:`quick-start-configuration-mode` issue the following commands: @@ -66,23 +72,30 @@ on specific addresses only. set service ssh port '22' -Configure DHCP/DNS Servers -########################## +.. _dhcp-dns-quick-start: + +DHCP/DNS quick-start +#################### -* Provide DHCP service on your internal/LAN network where VyOS will act - as the default gateway and DNS server. -* Client IP addresses are assigned from the range ``192.168.0.9 - - 192.168.0.254`` +The following settings will configure DHCP and DNS services on +your internal/LAN network, where VyOS will act as the default gateway and +DNS server. + +* The default gateway and DNS recursor address will be `192.168.0.1/24` +* The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for + static assignments +* DHCP clients will be assigned IP addresses within the range of + `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` * DHCP leases will hold for one day (86400 seconds) -* VyOS will server as full DNS recursor - no need to bother the Google or - Cloudflare DNS servers (good for privacy) -* Only clients from your internal/LAN network can use the DNS resolver +* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, + Cloudflare, or other public DNS servers (which is good for privacy) +* Only hosts from your internal/LAN network can use the DNS recursor .. code-block:: none set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1' set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 dns-server '192.168.0.1' - set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'internal-network' + set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'vyos.net' set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400' set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start 192.168.0.9 set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' @@ -95,7 +108,9 @@ Configure DHCP/DNS Servers NAT ### -* Configure :ref:`source-nat` for our internal/LAN network +The following settings will configure :ref:`source-nat` rules for our +internal/LAN network, allowing hosts to communicate through the outside/WAN +network via IP masquerade. .. code-block:: none @@ -129,7 +144,8 @@ which was not initiated from the internal/LAN side first. set firewall name OUTSIDE-LOCAL rule 20 state new 'enable' If you wanted to enable SSH access to your firewall from the outside/WAN -interface, you could create some additional rules to allow that kind of traffic. +interface, you could create some additional rules to allow that kind of +traffic. These rules allow SSH traffic and rate limit it to 4 requests per minute. This blocks brute-forcing attempts: @@ -170,8 +186,8 @@ Commit changes, save the configuration, and exit configuration mode: Hardening ######### -Especially if you are allowing SSH remote access from the outside/WAN interface, -there are a few additional configuration steps that should be taken. +Especially if you are allowing SSH remote access from the outside/WAN +interface, there are a few additional configuration steps that should be taken. Replace the default `vyos` system user: @@ -188,11 +204,25 @@ Set up :ref:`ssh_key_based_authentication`: Finally, try and SSH into the VyOS install as your new user. Once you have confirmed that your new user can access your router without a password, delete -the original ``vyos`` user and probably disable password authentication for -:ref:`ssh` at all: +the original ``vyos`` user and completely disable password authentication for +:ref:`ssh`: .. code-block:: none delete system login user vyos set service ssh disable-password-authentication +As above, commit your changes, save the configuration, and exit +configuration mode: + +.. code-block:: none + + vyos@vyos# commit + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + vyos@vyos# exit + vyos@vyos$ + +You now should have a simple yet secure and functioning router to experiment +with further. Enjoy!
\ No newline at end of file diff --git a/docs/routing/arp.rst b/docs/routing/arp.rst deleted file mode 100644 index 5f3115ab..00000000 --- a/docs/routing/arp.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _routing-arp: - -### -ARP -### - -:abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for -discovering the link layer address, such as a MAC address, associated with a -given internet layer address, typically an IPv4 address. This mapping is a -critical function in the Internet protocol suite. ARP was defined in 1982 by -:rfc:`826` which is Internet Standard STD 37. - -In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is -provided by the Neighbor Discovery Protocol (NDP). - -To manipulate or display ARP_ table entries, the following commands are -implemented. - -Configure -========= - -.. cfgcmd:: set protocols static arp <address> hwaddr <mac> - - This will configure a static ARP entry always resolving `<address>` to - `<mac>`. - - Example: - - .. code-block:: none - - set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa - -Operation -========= - -.. opcmd:: show protocols static arp - - Display all known ARP table entries spanning across all interfaces - -.. code-block:: none - - vyos@vyos:~$ show protocols static arp - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - - -.. opcmd:: show protocols static arp interface eth1 - - Display all known ARP table entries on a given interface only (`eth1`): - -.. code-block:: none - - vyos@vyos:~$ show protocols static arp interface eth1 - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - -.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst deleted file mode 100644 index 2c5e7089..00000000 --- a/docs/routing/bgp.rst +++ /dev/null @@ -1,335 +0,0 @@ -.. _bgp: - -### -BGP -### - -:abbr:`BGP (Border Gateway Protocol) is one of the Exterior Gateway Protocols -and the de facto standard interdomain routing protocol. The latest BGP version -is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` -adds multiprotocol support to BGP. - -VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank -them for their effort! - -Basic Concepts -============== - -.. _bgp-autonomous-systems: - -Autonomous Systems ------------------- - -From :rfc:`1930`: - - An AS is a connected group of one or more IP prefixes run by one or more - network operators which has a SINGLE and CLEARLY DEFINED routing policy. - -Each AS has an identifying number associated with it called an :abbr:`ASN -(Autonomous System Number)`. This is a two octet value ranging in value from 1 -to 65535. The AS numbers 64512 through 65535 are defined as private AS numbers. -Private AS numbers must not be advertised on the global Internet. - -The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of -BGP. BGP is a distance vector routing protocol, and the AS-Path framework -provides distance vector metric and loop detection to BGP. - -.. _bgp-address-families: - -Address Families ----------------- - -Multiprotocol extensions enable BGP to carry routing information for multiple -network layer protocols. BGP supports an Address Family Identifier (AFI) for -IPv4 and IPv6. - -.. _bgp-route-selection: - -Route Selection ---------------- - -The route selection process used by FRR's BGP implementation uses the following -decision criterion, starting at the top of the list and going towards the -bottom until one of the factors can be used. - -1. **Weight check** - - Prefer higher local weight routes to lower routes. - -2. **Local preference check** - - Prefer higher local preference routes to lower. - -3. **Local route check** - - Prefer local routes (statics, aggregates, redistributed) to received routes. - -4. **AS path length check** - - Prefer shortest hop-count AS_PATHs. - -5. **Origin check** - - Prefer the lowest origin type route. That is, prefer IGP origin routes to - EGP, to Incomplete routes. - -6. **MED check** - - Where routes with a MED were received from the same AS, prefer the route - with the lowest MED. - -7. **External check** - - Prefer the route received from an external, eBGP peer over routes received - from other types of peers. - -8. **IGP cost check** - - Prefer the route with the lower IGP cost. - -9. **Multi-path check** - - If multi-pathing is enabled, then check whether the routes not yet - distinguished in preference may be considered equal. If - :cfgcmd:`bgp bestpath as-path multipath-relax` is set, all such routes are - considered equal, otherwise routes received via iBGP with identical AS_PATHs - or routes received from eBGP neighbours in the same AS are considered equal. - -10. **Already-selected external check** - - Where both routes were received from eBGP peers, then prefer the route - which is already selected. Note that this check is not applied if - :cfgcmd:`bgp bestpath compare-routerid` is configured. This check can - prevent some cases of oscillation. - -11. **Router-ID check** - - Prefer the route with the lowest `router-ID`. If the route has an - `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is - used, otherwise the `router-ID` of the peer the route was received from is - used. - -12. **Cluster-List length check** - - The route with the shortest cluster-list length is used. The cluster-list - reflects the iBGP reflection path the route has taken. - -13. **Peer address** - - Prefer the route received from the peer with the higher transport layer - address, as a last-resort tie-breaker. - -.. _bgp-capability-negotiation: - -Capability Negotiation ----------------------- - -When adding IPv6 routing information exchange feature to BGP. There were some -proposals. :abbr:`IETF (Internet Engineering Task Force)` -:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol -Extension for BGP. The specification is described in :rfc:`2283`. The protocol -does not define new protocols. It defines new attributes to existing BGP. When -it is used exchanging IPv6 routing information it is called BGP-4+. When it is -used for exchanging multicast routing information it is called MBGP. - -*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports -the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. - -Traditional BGP did not have the feature to detect a remote peer's -capabilities, e.g. whether it can handle prefix types other than IPv4 unicast -routes. This was a big problem using Multiprotocol Extension for BGP in an -operational network. :rfc:`2842` adopted a feature called Capability -Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's -capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* -does not send these Capability Negotiation packets (at least not unless other -optional BGP features require capability negotiation). - -By default, FRR will bring up peering with minimal common capability for the -both sides. For example, if the local router has unicast and multicast -capabilities and the remote router only has unicast capability the local router -will establish the connection with unicast only capability. When there are no -common capabilities, FRR sends Unsupported Capability error and then resets the -connection. - -.. _bgp-router-configuration: - -BGP Router Configuration -======================== - -ASN and Router ID ------------------ - -.. cfgcmd:: set protocols bgp <asn> - - First of all you must configure BGP router with the :abbr:`ASN (Autonomous - System Number)`. The AS number is an identifier for the autonomous system. - The BGP protocol uses the AS number for detecting whether the BGP connection - is internal or external. - -.. cfgcmd:: set protocols bgp <asn> parameters router-id - - This command specifies the router-ID. If router ID is not specified it will - use the highest interface IP address. - -Route Selection ---------------- - -.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path confed - - This command specifies that the length of confederation path sets and - sequences should be taken into account during the BGP best path - decision process. - -.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path multipath-relax - - This command specifies that BGP decision process should consider paths - of equal AS_PATH length candidates for multipath computation. Without - the knob, the entire AS_PATH must match for multipath computation. - -.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path ignore - - Ignore AS_PATH length when selecting a route - -IPv4 -^^^^ - -A simple eBGP configuration: - -**Node 1:** - -.. code-block:: none - - set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' - set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' - set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' - set protocols bgp 65534 address-family ipv4-unicast network '172.16.0.0/16' - set protocols bgp 65534 parameters router-id '192.168.0.1' - -**Node 2:** - -.. code-block:: none - - set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' - set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' - set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' - set protocols bgp 65535 address-family ipv4-unicast network '172.17.0.0/16' - set protocols bgp 65535 parameters router-id '192.168.0.2' - - -Don't forget, the CIDR declared in the network statement MUST **exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -.. code-block:: none - - set protocols static route 172.16.0.0/16 blackhole distance '254' - -**Node 2:** - -.. code-block:: none - - set protocols static route 172.17.0.0/16 blackhole distance '254' - - -IPv6 -^^^^ - -A simple BGP configuration via IPv6. - -**Node 1:** - -.. code-block:: none - - set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' - set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' - set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast - set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' - set protocols bgp 65534 parameters router-id '10.1.1.1' - -**Node 2:** - -.. code-block:: none - - set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' - set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' - set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast - set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' - set protocols bgp 65535 parameters router-id '10.1.1.2' - -Don't forget, the CIDR declared in the network statement **MUST exist in your -routing table (dynamic or static), the best way to make sure that is true is -creating a static route:** - -**Node 1:** - -.. code-block:: none - - set protocols static route6 2001:db8:1::/48 blackhole distance '254' - -**Node 2:** - -.. code-block:: none - - set protocols static route6 2001:db8:2::/48 blackhole distance '254' - -Route Filter -^^^^^^^^^^^^ - -Route filter can be applied using a route-map: - -**Node1:** - -.. code-block:: none - - set policy prefix-list AS65535-IN rule 10 action 'permit' - set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' - set policy prefix-list AS65535-OUT rule 10 action 'deny' - set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' - set policy prefix-list6 AS65535-IN rule 10 action 'permit' - set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' - set policy prefix-list6 AS65535-OUT rule 10 action 'deny' - set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' - set policy route-map AS65535-IN rule 10 action 'permit' - set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 20 action 'deny' - set policy route-map AS65535-OUT rule 10 action 'deny' - set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 20 action 'permit' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' - -**Node2:** - -.. code-block:: none - - set policy prefix-list AS65534-IN rule 10 action 'permit' - set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' - set policy prefix-list AS65534-OUT rule 10 action 'deny' - set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' - set policy prefix-list6 AS65534-IN rule 10 action 'permit' - set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' - set policy prefix-list6 AS65534-OUT rule 10 action 'deny' - set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' - set policy route-map AS65534-IN rule 10 action 'permit' - set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 20 action 'deny' - set policy route-map AS65534-OUT rule 10 action 'deny' - set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 20 action 'permit' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' - -We could expand on this and also deny link local and multicast in the rule 20 -action deny. diff --git a/docs/routing/index.rst b/docs/routing/index.rst deleted file mode 100644 index a34bbfac..00000000 --- a/docs/routing/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _routing: - -####### -Routing -####### - -.. toctree:: - :maxdepth: 1 - - arp - bfd - bgp - mpls - mss-clamp - multicast - ospf - pbr - rip - routing-policy - rpki - static diff --git a/docs/routing/mpls.rst b/docs/routing/mpls.rst deleted file mode 100644 index c6d9d0fe..00000000 --- a/docs/routing/mpls.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _mpls: - -**** -MPLS -**** - - -Label Distribution Protocol -=========================== - - -.. note:: VyOS' MPLS support is not finished yet, its funcitionality is - limited. Currently it can only be configured as a P router, that is, - an LSR in the core of an MPLS network. - - -The **Multi-Protocol Label Switching** (MPLS) architecture does not -assume a single protocol to create MPLS paths. VyOS supports the Label -Distribution Protocol (LDP) as implemented by FRR, based on `RFC 5036 <https://tools.ietf.org/html/rfc5036.html>`__. - -LDT it is an MPLS signaling protocol that distributes labels creating -MPLS paths in a dynamic manner. LDT is not exactly a routing protocol, -as it relies on other routing protocols for forwarding decisions. - - -.. cfgcmd:: set protocols mpls ldp interface <interface> - - Use this command to enable LDP in the interface you define. - - -.. cfgcmd:: set protocols mpls ldp router-id <address> - - Use this command to configure the IP address used as the LDP - router-id of the local device - - -In order to allow the exchange of label advertisements required for LDP, -a TCP session should be established between routers. Routers will need -to learn each other's **transport address** in order to establish the -TCP session. - -You may want to use the same address for both the LDP router-id and the -discovery transport address, but for VyOS MPLS LDP to work both -parameters must be explicitely set in the configuration. - - -.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address | transport-ipv6-address <address> - - Use this command to set the IPv4 or IPv6 transport-address used by - LDP. - -.. cfgcmd:: set protocols mpls ldp neighbor <address> password <password> - - Use this command to configure authentication for LDP peers. Set the - IP address of the LDP peer and a password that should be shared in - order to become neighbors. - - -Example -------- - -.. code-block:: none - - set interfaces dummy dum0 address '2.2.2.2/32' - set interfaces ethernet eth1 address '10.0.0.2/24' - set interfaces ethernet eth2 address '10.0.255.1/24' - set protocols mpls ldp discovery transport-ipv4-address '2.2.2.2' - set protocols mpls ldp interface 'eth1' - set protocols mpls ldp interface 'eth2' - set protocols mpls ldp router-id '2.2.2.2' - set protocols ospf area 0 network '0.0.0.0/0' - set protocols ospf parameters router-id '2.2.2.2' - - -show commands -------------- - -When LDP is working, you will be able to see label information in the -outcome of ``show ip route``. Besides that information, there are also -specific *show* commands for LDP: - - -.. opcmd:: show mpls ldp binding - - Use this command to see the Label Information Base. - - -.. opcmd:: show mpls ldp discovery - - Use this command to see Discovery Hello information - - -.. opcmd:: show mpls ldp interface - - Use this command to see LDP interface information - - -.. opcmd:: show mpls ldp neighbor - - Uset this command to see LDP neighbor information - - -.. opcmd:: show mpls ldp neighbor detail - - Uset this command to see detailed LDP neighbor information - - diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst deleted file mode 100644 index 923b1338..00000000 --- a/docs/routing/mss-clamp.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _routing-mss-clamp: - -TCP-MSS Clamping ----------------- - -As Internet wide PMTU discovery rarely works we sometimes need to clamp our TCP -MSS value to a specific value. Starting with VyOS 1.2 there is a firewall option -to clamp your TCP MSS value for IPv4 and IPv6. - -Clamping can be disabled per interface using the `disable` keyword: - -.. code-block:: none - - set firewall options interface pppoe0 disable - -IPv4 -^^^^ - -Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and `1372` -for your WireGuard `wg02` tunnel. - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss '1452' - set firewall options interface wg02 adjust-mss '1372' - -IPv6 -^^^^^ - -Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and -`wg02` interface. - -To achieve the same for IPv6 please use: - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss6 '1280' - set firewall options interface wg02 adjust-mss6 '1280' - -.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in 1452 - bytes on a 1492 byte MTU. diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst deleted file mode 100644 index fbe8984f..00000000 --- a/docs/routing/ospf.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _routing-ospf: - -OSPF ----- - -:abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet -Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls -into the group of interior gateway protocols (IGPs), operating within a single -autonomous system (AS). It is defined as OSPF Version 2 in :rfc:`2328` (1998) -for IPv4. Updates for IPv6 are specified as OSPF Version 3 in :rfc:`5340` -(2008). OSPF supports the :abbr:`CIDR (Classless Inter-Domain Routing)` -addressing model. - -OSPF is a widely used IGP in large enterprise networks. - -OSPFv2 (IPv4) -^^^^^^^^^^^^^ - -In order to have a VyOS system exchanging routes with OSPF neighbors, you will -at least need to configure an OSPF area and some network. - -.. code-block:: none - - set protocols ospf area 0 network 192.168.0.0/24 - -That is the minimum configuration you will need. -It is a good practice to define the router ID too. - -.. code-block:: none - - set protocols ospf parameters router-id 10.1.1.1 - - -Below you can see a typical configuration using 2 nodes, redistribute loopback -address and the node 1 sending the default route: - -**Node 1** - -.. code-block:: none - - set interfaces loopback lo address 10.1.1.1/32 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf default-information originate always - set protocols ospf default-information originate metric 10 - set protocols ospf default-information originate metric-type 2 - set protocols ospf log-adjacency-changes - set protocols ospf parameters router-id 10.1.1.1 - set protocols ospf redistribute connected metric-type 2 - set protocols ospf redistribute connected route-map CONNECT - - set policy route-map CONNECT rule 10 action permit - set policy route-map CONNECT rule 10 match interface lo - -**Node 2** - -.. code-block:: none - - set interfaces loopback lo address 10.2.2.2/32 - set protocols ospf area 0 network 192.168.0.0/24 - set protocols ospf log-adjacency-changes - set protocols ospf parameters router-id 10.2.2.2 - set protocols ospf redistribute connected metric-type 2 - set protocols ospf redistribute connected route-map CONNECT - - set policy route-map CONNECT rule 10 action permit - set policy route-map CONNECT rule 10 match interface lo - -OSPFv3 (IPv6) -^^^^^^^^^^^^^ - -A typical configuration using 2 nodes. - -**Node 1:** - -.. code-block:: none - - set protocols ospfv3 area 0.0.0.0 interface eth1 - set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 - set protocols ospfv3 parameters router-id 192.168.1.1 - set protocols ospfv3 redistribute connected - -**Node 2:** - -.. code-block:: none - - set protocols ospfv3 area 0.0.0.0 interface eth1 - set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 - set protocols ospfv3 parameters router-id 192.168.2.1 - set protocols ospfv3 redistribute connected - -.. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard - interface link. This requires you to configure link-local addresses manually - on the WireGuard interfaces, see :vytask:`T1483`. - -Example configuration for WireGuard interfaces: - -**Node 1** - -.. code-block:: none - - set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' - set interfaces wireguard wg01 address '192.168.0.1/24' - set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' - set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' - set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' - set interfaces wireguard wg01 port '12345' - set protocols ospfv3 parameters router-id 192.168.1.1 - set protocols ospfv3 area 0.0.0.0 interface 'wg01' - set protocols ospfv3 area 0.0.0.0 interface 'lo' - -**Node 2** - -.. code-block:: none - - set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' - set interfaces wireguard wg01 address '192.168.0.2/24' - set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' - set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' - set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' - set interfaces wireguard wg01 port '12345' - set protocols ospfv3 parameters router-id 192.168.1.2 - set protocols ospfv3 area 0.0.0.0 interface 'wg01' - set protocols ospfv3 area 0.0.0.0 interface 'lo' - -**Status** - -.. code-block:: none - - vyos@ospf01:~$ sh ipv6 ospfv3 neighbor - Neighbor ID Pri DeadTime State/IfState Duration I/F[State] - 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] - - vyos@ospf02# run sh ipv6 ospfv3 neighbor - Neighbor ID Pri DeadTime State/IfState Duration I/F[State] - 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] - diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst deleted file mode 100644 index 797f79e3..00000000 --- a/docs/routing/pbr.rst +++ /dev/null @@ -1,105 +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. diff --git a/docs/routing/rip.rst b/docs/routing/rip.rst deleted file mode 100644 index 9cf4f289..00000000 --- a/docs/routing/rip.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _rip: - -RIP ---- - -:abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway -protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS -routing protocol. RIP is a distance-vector protocol and is based on the -Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates -to its neighbors periodically, thus allowing the convergence to a known -topology. In each update, the distance to any given network will be broadcast -to its neighboring router. - -Supported versions of RIP are: -* RIPv1 as described in :rfc:`1058` -* RIPv2 as described in :rfc:`2453` - -Simple RIP configuration using 2 nodes and redistributing connected interfaces. - -**Node 1:** - -.. code-block:: none - - set interfaces loopback address 10.1.1.1/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected - -**Node 2:** - -.. code-block:: none - - set interfaces loopback address 10.2.2.2/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected diff --git a/docs/routing/routing-policy.rst b/docs/routing/routing-policy.rst deleted file mode 100644 index 461e42d8..00000000 --- a/docs/routing/routing-policy.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -Routing-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 - -Routing Policy 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' <<<< *** - - *** get 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 < longer AS_path length - - Total number of prefixes 1 - vyos@vos1:~$ diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst deleted file mode 100644 index 5c154fdf..00000000 --- a/docs/services/dns-forwarding.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. _dns-forwarding: - -############## -DNS Forwarding -############## - -Configuration -============= - -VyOS provides DNS infrastructure for small networks. It is designed to be -lightweight and have a small footprint, suitable for resource constrained -routers and firewalls, for this we utilize PowerDNS recursor. - -The VyOS DNS forwarder does not require an upstream DNS server. It can serve as a -full recursive DNS server - but it can also forward queries to configurable -upstream DNS servers. By not configuring any upstream DNS servers you also -avoid to be tracked by the provider of your upstream DNS server. - -.. cfgcmd:: set service dns forwarding system - - Forward incoming DNS queries to the DNS servers configured under the ``system - name-server`` nodes. - -.. cfgcmd:: set service dns forwarding name-server <address> - - Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. - You can configure multiple nameservers here. - -.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - - Forward received queries for a particular domain (specified via `domain-name`) - to a given name-server. Multiple nameservers can be specified. You can use - this feature for a DNS split-horizon configuration. - - .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). - -.. cfgcmd:: set service dns forwarding allow-from <network> - - Given the fact that open DNS recursors could be used on DDOS amplification - attacts, you must configure the networks which are allowed to use this - recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and - IPv6 networks to query this server. This is on general a bad idea. - -.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> - - The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can - be set with the dnssec setting. In order from least to most processing, these - are: - - * **off** In this mode, no DNSSEC processing takes place. The recursor will - not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the - DO and AD bits in queries. - - * **process-no-validate** In this mode the Recursor acts as a "security - aware, non-validating" nameserver, meaning it will set the DO-bit on - outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to - clients that ask for them (by means of a DO-bit in the query), except for - zones provided through the auth-zones setting. It will not do any - validation in this mode, not even when requested by the client. - - * **process** When dnssec is set to process the behaviour is similar to - process-no-validate. However, the recursor will try to validate the data - if at least one of the DO or AD bits is set in the query; in that case, - it will set the AD-bit in the response when the data is validated - successfully, or send SERVFAIL when the validation comes up bogus. - - * **log-fail** In this mode, the recursor will attempt to validate all data - it retrieves from authoritative servers, regardless of the client's DNSSEC - desires, and will log the validation result. This mode can be used to - determine the extra load and amount of possibly bogus answers before - turning on full-blown validation. Responses to client queries are the same - as with process. - - * **validate** The highest mode of DNSSEC processing. In this mode, all - queries will be validated and will be answered with a SERVFAIL in case of - bogus data, regardless of the client's request. - - .. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. - This might lead to unexpected query results when testing. Set ``+noad`` - on the ``dig`` commandline when this is the case. - - .. note:: The ``CD``-bit is honored correctly for process and validate. For - log-fail, failures will be logged too. - -.. cfgcmd:: set service dns forwarding ignore-hosts-file - - Do not use local ``/etc/hosts`` file in name resolution. VyOS DHCP server - will use this file to add resolvers to assigned addresses. - -.. cfgcmd:: set service dns forwarding max-cache-entries - - Maximum number of DNS cache entries. 1 million per CPU core will generally - suffice for most installations. - -.. cfgcmd:: set service dns forwarding negative-ttl - - A query for which there is authoritatively no answer is cached to quickly - deny a record's existence later on, without putting a heavy load on the - remote server. In practice, caches can become saturated with hundreds of - thousands of hosts which are tried only once. This setting, which defaults - to 3600 seconds, puts a maximum on the amount of time negative entries are - cached. - -.. cfgcmd:: set service dns forwarding listen-address - - The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder will listen on this address for - incoming connections. - -Example -======= - -A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to implement a split-horizon DNS configuration for example.com. - -In this scenario: - -* All DNS requests for example.com must be forwarded to a DNS server at 192.0.2.254 - and 2001:db8:cafe::1 -* All other DNS requests will be forwarded to a different set of DNS servers at 192.0.2.1, - 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff -* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) interface addresses - 192.168.1.254 - for IPv4 and 2001:db8::ffff for IPv6 -* The VyOS DNS forwarder will only accept lookup requests from the LAN subnets - 192.168.1.0/24 and 2001:db8::/64 - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.254 - set service dns forwarding domain example.com server 2001:db8:cafe::1 - set service dns forwarding name-server 192.0.2.1 - set service dns forwarding name-server 192.0.2.2 - set service dns forwarding name-server 2001:db8::1:ffff - set service dns forwarding name-server 2001:db8::2:ffff - set service dns forwarding listen-address 192.168.1.254 - set service dns forwarding listen-address 2001:db8::ffff - set service dns forwarding allow-from 192.168.1.0/24 - set service dns forwarding allow-from 2001:db8::/64 - -Operation -========= - -.. opcmd:: reset dns forwarding <all | domain> - - Resets the local DNS forwarding cache database. You can reset the cache for all - entries or only for entries to a specific domain. - -.. opcmd:: restart dns forwarding - - Restarts the DNS recursor process. This also invalidates the local DNS forwarding cache. diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst deleted file mode 100644 index 3d802d29..00000000 --- a/docs/services/dynamic-dns.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _dynamic-dns: - -########### -Dynamic DNS -########### - -VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a Perl script written for -this only one purpose. - -ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second -one involves a third party service, like DynDNS.com or any other similar -website. This method uses HTTP requests to transmit the new IP address. You -can configure both in VyOS. - -Configuration -============= - -:rfc:`2136` Based ------------------ - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> - - Create new :rfc:`2136` DNS update configuration which will update the IP - address assigned to `<interface>` on the service you configured under - `<service-name>`. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile> - - File identified by `<keyfile>` containing the secret RNDC key shared with - remote DNS server. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> - - Configure the DNS `<server>` IP/FQDN used when updating this dynamic - assignment. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> - - Configure DNS `<zone>` to be updated. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> - - Configure DNS `<record>` which should be updated. This can be set multiple - times. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> - - Configure optional TTL value on the given resource record. This defualts to - 600 seconds. - -Example -^^^^^^^ - -* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` -* Use auth key file at ``/config/auth/my.key`` -* Set TTL to 300 seconds - -.. code-block:: none - - vyos@vyos# show service dns dynamic - interface eth0.7 { - rfc2136 VyOS-DNS { - key /config/auth/my.key - record example.vyos.io - server ns1.vyos.io - ttl 300 - zone vyos.io - } - } - -This will render the following ddclient_ configuration entry: - -.. code-block:: none - - # - # ddclient configuration for interface "eth0.7": - # - use=if, if=eth0.7 - - # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io - server=ns1.vyos.io - protocol=nsupdate - password=/config/auth/my.key - ttl=300 - zone=vyos.io - example.vyos.io - -.. note:: You can also keep different DNS zone updated. Just create a new - config node: ``set service dns dynamic interface <interface> rfc2136 - <other-service-name>`` - -HTTP based services -------------------- - -VyOS is also able to use any service relying on protocols supported by ddclient. - -To use such a service, one must define a login, password, one or multiple -hostnames, protocol and server. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname> - - Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS - provider identified by `<service>` when the IP address on interface - `<interface>` changes. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> - - Configure `<username>` used when authenticating the update request for - DynDNS service identified by `<service>`. - For Namecheap, set the <domain> you wish to update. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> - - Configure `<password>` used when authenticating the update request for - DynDNS service identified by `<service>`. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol> - - When a ``custom`` DynDNS provider is used the protocol used for communicating - to the provider must be specified under `<protocol>`. See the embedded - completion helper for available protocols. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server> - - When a ``custom`` DynDNS provider is used the `<server>` where update - requests are being sent to must be specified. - -Example: -^^^^^^^^ - -Use DynDNS as your preferred provider: - -.. code-block:: none - - set service dns dynamic interface eth0 service dyndns - set service dns dynamic interface eth0 service dyndns login my-login - set service dns dynamic interface eth0 service dyndns password my-password - set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname - -.. note:: Multiple services can be used per interface. Just specify as many - serives per interface as you like! - -Running Behind NAT ------------------- - -By default, ddclient_ will update a dynamic dns record using the IP address -directly attached to the interface. If your VyOS instance is behind NAT, your -record will be updated to point to your internal IP. - -ddclient_ has another way to determine the WAN IP address. This is controlled -by: - -.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> - - Use configured `<url>` to determine your IP address. ddclient_ will load - `<url>` and tries to extract your IP address from the response. - -.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> - - ddclient_ will skip any address located before the string set in `<pattern>`. - -.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/services/index.rst b/docs/services/index.rst deleted file mode 100644 index 76520b52..00000000 --- a/docs/services/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _services: - -######## -Services -######## - -This chapter describes the available system/network services provided by VyOS. - -.. toctree:: - :maxdepth: 1 - - conntrack - console-server - dhcp - dns-forwarding - dynamic-dns - lldp - mdns-repeater - ipoe-server - pppoe-server - udp-broadcast-relay - router-advert - snmp - ssh - tftp - webproxy diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst deleted file mode 100644 index c5959e5c..00000000 --- a/docs/services/ssh.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _ssh: - -### -SSH -### - -:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating -network services securely over an unsecured network. The standard TCP port for -SSH is 22. The best known example application is for remote login to computer -systems by users. - -SSH provides a secure channel over an unsecured network in a client-server -architecture, connecting an SSH client application with an SSH server. Common -applications include remote command-line login and remote command execution, -but any network service can be secured with SSH. The protocol specification -distinguishes between two major versions, referred to as SSH-1 and SSH-2. - -The most visible application of the protocol is for access to shell accounts -on Unix-like operating systems, but it sees some limited use on Windows as -well. In 2015, Microsoft announced that they would include native support for -SSH in a future release. - -SSH was designed as a replacement for Telnet and for unsecured remote shell -protocols such as the Berkeley rlogin, rsh, and rexec protocols. -Those protocols send information, notably passwords, in plaintext, -rendering them susceptible to interception and disclosure using packet -analysis. The encryption used by SSH is intended to provide confidentiality -and integrity of data over an unsecured network, such as the Internet. - -Configuration -============= - -.. cfgcmd:: set service ssh port <port> - -Enabling SSH only requires you to specify the port ``<port>`` you want SSH to -listen on. By default, SSH runs on port 22. - -.. cfgcmd:: set service ssh listen-address <address> - -Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be -defined. - -.. cfgcmd:: set service ssh ciphers <cipher> - -Define allowed ciphers used for the SSH connection. A number of allowed ciphers -can be specified, use multiple occurrences to allow multiple ciphers. You can -choose from the following ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, -``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, ``arcfour128``, -``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` - -.. cfgcmd:: set service ssh disable-password-authentication - -Disable password based authentication. Login via SSH keys only. This hardens -security! - -.. cfgcmd:: set service ssh disable-host-validation - -Disable the host validation through reverse DNS lookups - can speedup login -time when reverse lookup is not possible. - -.. cfgcmd:: set service ssh macs <mac> - -Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. -The MAC algorithm is used in protocol version 2 for data integrity protection. -Multiple algorithms can be provided. Supported MACs: ``hmac-md5``, -``hmac-md5-96``, ``hmac-ripemd160``, ``hmac-sha1``, ``hmac-sha1-96``, -``hmac-sha2-256``, ``hmac-sha2-512``, ``umac-64@openssh.com``, -``umac-128@openssh.com``, ``hmac-md5-etm@openssh.com``, -``hmac-md5-96-etm@openssh.com``, ``hmac-ripemd160-etm@openssh.com``, -``hmac-sha1-etm@openssh.com``, ``hmac-sha1-96-etm@openssh.com``, -``hmac-sha2-256-etm@openssh.com``, ``hmac-sha2-512-etm@openssh.com``, -``umac-64-etm@openssh.com``, ``umac-128-etm@openssh.com`` - -.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due - to tighter security in VyOS 1.2. - -.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> - -Add access-control directive to allow or deny users and groups. Directives are -processed in the following order of precedence: ``deny-users``, ``allow-users``, -``deny-groups`` and ``allow-groups``. - -.. cfgcmd:: set service ssh client-keepalive-interval <interval> - -Specify timeout interval for keepalive message in seconds. - -.. cfgcmd:: set service ssh key-exchange <kex> - -Specify allowed :abbr:`KEX (Key Exchange)` algorithms. -Supported algorithms: ``diffie-hellman-group1-sha1``, -``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, -``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, -``diffie-hellman-group-exchange-sha1``, -``diffie-hellman-group-exchange-sha256``, ``ecdh-sha2-nistp256``, -``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, ``curve25519-sha256`` and -``curve25519-sha256@libssh.org``. - -.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> - -Set the ``sshd`` log level. The default is ``info``. - -.. cmfcmd:: set service ssh vrf <name> - -Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -.. seealso:: SSH :ref:`ssh_key_based_authentication` diff --git a/docs/services/webproxy.rst b/docs/services/webproxy.rst deleted file mode 100644 index 654e73f2..00000000 --- a/docs/services/webproxy.rst +++ /dev/null @@ -1,153 +0,0 @@ -Webproxy --------- - -The proxy service in VyOS is based on Squid3 and some related modules. - -Squid3_ is a caching and forwarding HTTP web proxy. It has a wide variety of -uses, including speeding up a web server by caching repeated requests, -caching web, DNS and other computer network lookups for a group of people -sharing network resources, and aiding security by filtering traffic. Although -primarily used for HTTP and FTP, Squid includes limited support for several -other protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does -not support the SOCKS protocol. - -All examples here assumes that your inside ip address is ``192.168.0.1``. -Replace with your own where applicable. - -URL Filtering is provided by Squidguard_. - -Configuration -^^^^^^^^^^^^^^ - -.. code-block:: none - - # Enable proxy service - set service webproxy listen-address 192.168.0.1 - - # By default it will listen to port 3128. If you want something else you have to define that. - set service webproxy listen-address 192.168.0.1 port 2050 - - # By default the transparent proxy on that interface is enabled. To disable that you simply - set service webproxy listen-address 192.168.0.1 disable-transparent - - # Block specific urls - set service webproxy url-filtering squidguard local-block myspace.com - - # If you want to you can log these blocks - set service webproxy url-filtering squidguard log local-block - - -Options -******* - -Filtering by category -^^^^^^^^^^^^^^^^^^^^^ - -If you want to use existing blacklists you have to create/download a database -first. Otherwise you will not be able to commit the config changes. - -.. code-block:: none - - vyos@vyos# commit - [ service webproxy ] - Warning: no blacklists installed - Unknown block-category [ads] for policy [default] - - [[service webproxy]] failed - Commit failed - -* Download/Update complete blacklist - - :code:`update webproxy blacklists` - -* Download/Update partial blacklist - - :code:`update webproxy blacklists category ads` - - Use tab completion to get a list of categories. - -* To auto update the blacklist files - - :code:`set service webproxy url-filtering squidguard auto-update update-hour 23` - -* To configure blocking add the following to the configuration - - :code:`set service webproxy url-filtering squidguard block-category ads` - - :code:`set service webproxy url-filtering squidguard block-category malware` - -Authentication -^^^^^^^^^^^^^^ - -The embedded Squid proxy can use LDAP to authenticate users against a company -wide directory. The following configuration is an example of how to use Active -Directory as authentication backend. Queries are done via LDAP. - -.. code-block:: none - - vyos@vyos# show service webproxy - authentication { - children 5 - credentials-ttl 60 - ldap { - base-dn DC=example,DC=local - bind-dn CN=proxyuser,CN=Users,DC=example,DC=local - filter-expression (cn=%s) - password Qwert1234 - server ldap.example.local - username-attribute cn - } - method ldap - realm "VyOS Webproxy" - } - cache-size 100 - default-port 3128 - listen-address 192.168.188.103 { - disable-transparent - } - -* ``base-dn`` set the base directory for the search -* ``bind-dn`` and ``password``: set the user, which is used for the ldap search -* ``filter-expression``: set the exact filter which a authorized user match in a ldap-search. In this example every User is able to authorized. - -You can find more about the ldap authentication `here <http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ - -Adjusting cache size -^^^^^^^^^^^^^^^^^^^^ - -The size of the proxy cache can be adjusted by the user. - -.. code-block:: none - - set service webproxy cache-size - Possible completions: - <0-4294967295> - Disk cache size in MB (default 100) - 0 Disable disk caching - 100 - -Bypassing the webproxy -^^^^^^^^^^^^^^^^^^^^^^ - -Some services don't work correctly when being handled via a web proxy. -So sometimes it is useful to bypass a transparent proxy: - -* To bypass the proxy for every request that is directed to a specific - destination: - - :code:`set service webproxy whitelist destination-address 198.51.100.33` - - :code:`set service webproxy whitelist destination-address 192.0.2.0/24` - - -* To bypass the proxy for every request that is coming from a specific source: - - :code:`set service webproxy whitelist source-address 192.168.1.2` - - :code:`set service webproxy whitelist source-address 192.168.2.0/24` - - (This can be useful when a called service has many and/or often changing - destination addresses - e.g. Netflix.) - -.. _Squid3: http://www.squid-cache.org/ -.. _Squidguard: http://www.squidguard.org/ diff --git a/docs/system/advanced-index.rst b/docs/system/advanced-index.rst deleted file mode 100644 index 36469763..00000000 --- a/docs/system/advanced-index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _advanced_system_tweaks: - -###################### -Advanced System Tweaks -###################### - -.. toctree:: - :maxdepth: 2 - - eventhandler - flow-accounting - ntp - options - proxy - serial-console - syslog - task-scheduler - lcd diff --git a/docs/system/basic-index.rst b/docs/system/basic-index.rst deleted file mode 100644 index cb030089..00000000 --- a/docs/system/basic-index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _basic_system_tweaks: - -################### -Basic System Tweaks -################### - -.. toctree:: - :maxdepth: 2 - - user-management - host-information - default-route - time-zone diff --git a/docs/system/options.rst b/docs/system/options.rst deleted file mode 100644 index 82ad4801..00000000 --- a/docs/system/options.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _system_options: - -####### -Options -####### - -This chapter describe the possibilities of advanced system behavior. - -General -####### - -.. cfgcmd:: set system options beep-if-fully-booted - - Send an audible beep to the system speaker when system is ready. - -.. cfgcmd:: set system options ctrl-alt-del-action [ ignore | reboot | poweroff ] - - Action which will be run once the ctrl-alt-del keystroke is received. - -.. cfgcmd:: set system options reboot-on-panic - - Automatically teboot system on kernel panic after 60 seconds. - -HTTP client -########### - -.. cfgcmd:: set system options http-client source-address <address> - - Several commands utilize curl to initiate transfers. Configure the local - source IPv4/IPv6 address used for all CURL operations. - -.. cfgcmd:: set system options http-client source-interface <interface> - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. - -.. note:: `source-address` and `source-interface` can not be used at the same time. - - diff --git a/docs/troubleshooting.rst b/docs/troubleshooting/index.rst index 23248507..a965dbe6 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting/index.rst @@ -155,6 +155,48 @@ Neighbor Discovery 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 ********** @@ -362,6 +404,8 @@ to clear counters on firewall rulesets or single rules System Information ****************** +.. _boot-steps: + Boot Steps ========== @@ -401,6 +445,8 @@ These are the boot steps for VyOS 1.2 11. Finally it runs the post-config script ``/config/scripts/vyos-postconfig-bootup.script`` +.. stop_vyoslinter + .. _Quagga: https://www.quagga.net/ .. _`GNU Zebra`: https://www.gnu.org/software/zebra/ .. _FRR: https://frrouting.org/ @@ -409,3 +455,5 @@ These are the boot steps for VyOS 1.2 .. _`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 + +.. start_vyoslinter diff --git a/docs/vpn/dmvpn.rst b/docs/vpn/dmvpn.rst deleted file mode 100644 index c4f53a72..00000000 --- a/docs/vpn/dmvpn.rst +++ /dev/null @@ -1,415 +0,0 @@ -.. _vpn-dmvpn: - -DMVPN ------ - -**D** ynamic **M** ultipoint **V** irtual **P** rivate **N** etworking - -DMVPN is a dynamic VPN technology originally developed by Cisco. While their -implementation was somewhat proprietary, the underlying technologies are -actually standards based. The three technologies are: - -* **NHRP** - NBMA Next Hop Resolution Protocol :rfc:`2332` -* **mGRE** - Multipoint Generic Routing Encapsulation / mGRE :rfc:`1702` -* **IPSec** - IP Security (too many RFCs to list, but start with :rfc:`4301`) - -NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint -registration, and endpoint discovery/lookup), mGRE provides the tunnel -encapsulation itself, and the IPSec protocols handle the key exchange, and -crypto mechanism. - -In short, DMVPN provides the capability for creating a dynamic-mesh VPN -network without having to pre-configure (static) all possible tunnel end-point -peers. - -.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A - complete solution also incorporates the use of a routing protocol. BGP is - particularly well suited for use with DMVPN. - -Baseline Configuration: - -**STEPS:** - -#. Create tunnel config (`interfaces tunnel`) -#. Create nhrp (`protocols nhrp`) -#. Create ipsec vpn (optional, but recommended for security) (`vpn ipsec`) - -The tunnel will be set to mGRE if for encapsulation `gre` is set, and no -`remote-ip` is set. If the public ip is provided by DHCP the tunnel `local-ip` -can be set to "0.0.0.0". If you do set the `remote-ip` directive at any point, the interface will need to be `delete`'d from the config and recreated without the `remote-ip` config ever being set. - -.. figure:: ../_static/images/vpn_dmvpn_topology01.png - :scale: 40 % - :alt: Baseline DMVPN topology - - Baseline DMVPN topology - -HUB Configuration -^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - interfaces - tunnel <tunN> { - address <ipv4> - encapsulation gre - local-ip <public ip> - multicast enable - description <txt> - parameters { - ip { - <usual IP options> - } - } - } - } - protocols { - nhrp { - tunnel <tunN> { - cisco-authentication <key phrase> - holding-time <seconds> - multicast dynamic - redirect - } - } - } - vpn { - ipsec { - esp-group <text> { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group <text> { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface <ethN> - } - profile <text> { - authentication { - mode pre-shared-secret - pre-shared-secret <key phrase> - } - bind { - tunnel <tunN> - } - esp-group <text> - ike-group <text> - } - } - } - -HUB Example Configuration: - -.. code-block:: none - - set interfaces ethernet eth0 address '198.51.100.41/30' - set interfaces ethernet eth1 address '192.168.1.1/24' - set system host-name 'HUB' - - set interfaces tunnel tun0 address 10.0.0.1/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 198.51.100.41 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication SECRET - set protocols nhrp tunnel tun0 holding-time 300 - set protocols nhrp tunnel tun0 multicast dynamic - set protocols nhrp tunnel tun0 redirect - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-HUB proposal 1 - set vpn ipsec ike-group IKE-HUB proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-HUB proposal 1 hash sha1 - set vpn ipsec ike-group IKE-HUB proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-HUB proposal 2 hash sha1 - set vpn ipsec ike-group IKE-HUB lifetime 3600 - set vpn ipsec esp-group ESP-HUB proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-HUB proposal 1 hash sha1 - set vpn ipsec esp-group ESP-HUB proposal 2 encryption 3des - set vpn ipsec esp-group ESP-HUB proposal 2 hash md5 - set vpn ipsec esp-group ESP-HUB lifetime 1800 - set vpn ipsec esp-group ESP-HUB pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-HUB - set vpn ipsec profile NHRPVPN ike-group IKE-HUB - - set protocols static route 0.0.0.0/0 next-hop 1.1.1.2 - set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 - set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 - -HUB on AWS Configuration Specifics -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Setting this up on AWS will require a "Custom Protocol Rule" for protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC Network ACL, and secondly on the security group network ACL attached to the EC2 instance. This has been tested as working for the official AMI image on the AWS Marketplace. (Locate the correct VPC and security group by navigating through the details pane below your EC2 instance in the AWS console) - -SPOKE Configuration -^^^^^^^^^^^^^^^^^^^ - -SPOKE1 Configuration: - -.. code-block:: none - - interfaces - tunnel <tunN> { - address <ipv4> - encapsulation gre - local-ip <public ip> - multicast enable - description <txt> - parameters { - ip { - <usual IP options> - } - } - } - } - protocols { - nhrp { - tunnel <tunN> { - cisco-authentication <key phrase> - map <ipv4/net> { - nbma-address <ipv4> - register - } - holding-time <seconds> - multicast nhs - redirect - shortcut - } - } - } - vpn { - ipsec { - esp-group <text> { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group <text> { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface <ethN> - } - profile <text> { - authentication { - mode pre-shared-secret - pre-shared-secret <key phrase> - } - bind { - tunnel <tunN> - } - esp-group <text> - ike-group <text> - } - } - } - -SPOKE1 Example Configuration - -.. code-block:: none - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth1 address '192.168.2.1/24' - set system host-name 'SPOKE1' - - set interfaces tunnel tun0 address 10.0.0.2/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 0.0.0.0 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication 'SECRET' - set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 198.51.100.41 - set protocols nhrp tunnel tun0 map 10.0.0.1/24 'register' - set protocols nhrp tunnel tun0 multicast 'nhs' - set protocols nhrp tunnel tun0 'redirect' - set protocols nhrp tunnel tun0 'shortcut' - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-SPOKE proposal 1 - set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 - set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 - set vpn ipsec ike-group IKE-SPOKE lifetime 3600 - set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 - set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des - set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 - set vpn ipsec esp-group ESP-SPOKE lifetime 1800 - set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE - set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE - - set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 - set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 - - -SPOKE2 Configuration - -.. code-block:: none - - interfaces - tunnel <tunN> { - address <ipv4> - encapsulation gre - local-ip <public ip> - multicast enable - description <txt> - parameters { - ip { - <usual IP options> - } - } - } - } - protocols { - nhrp { - tunnel <tunN> { - cisco-authentication <key phrase> - map <ipv4/net> { - nbma-address <ipv4> - register - } - holding-time <seconds> - multicast nhs - redirect - shortcut - } - } - } - vpn { - ipsec { - esp-group <text> { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group <text> { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface <ethN> - } - profile <text> { - authentication { - mode pre-shared-secret - pre-shared-secret <key phrase> - } - bind { - tunnel <tunN> - } - esp-group <text> - ike-group <text> - } - } - } - -SPOKE2 Example Configuration - -.. code-block:: none - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth1 address '192.168.3.1/24' - set system host-name 'SPOKE2' - - set interfaces tunnel tun0 address 10.0.0.3/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 0.0.0.0 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication SECRET - set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 198.51.100.41 - set protocols nhrp tunnel tun0 map 10.0.0.1/24 register - set protocols nhrp tunnel tun0 multicast nhs - set protocols nhrp tunnel tun0 redirect - set protocols nhrp tunnel tun0 shortcut - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-SPOKE proposal 1 - set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 - set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 - set vpn ipsec ike-group IKE-SPOKE lifetime 3600 - set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 - set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des - set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 - set vpn ipsec esp-group ESP-SPOKE lifetime 1800 - set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE - set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE - - set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 - set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst deleted file mode 100644 index 42a90a3f..00000000 --- a/docs/vpn/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _vpn: - -### -VPN -### - -.. toctree:: - :maxdepth: 2 - - dmvpn - gre-ipsec - l2tp - openvpn - pptp - site2site_ipsec - sstp - wireguard diff --git a/requirements.txt b/requirements.txt index fc8e190e..03b34c63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ Sphinx>=1.4.3 sphinx-rtd-theme setuptools docutils +lxml sphinx-notfound-page @@ -1,11 +1,11 @@ -StylesPath = ci/vale +StylesPath = .github/styles MinAlertLevel = suggestion SkippedScopes = script, style, pre, figure, img, a, code [*.rst] -BasedOnStyles = VyOS +BasedOnStyles = VyOS, Google Google.DateFormat = YES vale.GenderBias = NO @@ -13,4 +13,4 @@ vale.Hedging = NO vale.Redundancy = NO vale.Repetition = YES vale.Uncomparables = NO -proselint.GenderBias = NO +proselint.GenderBias = NO
\ No newline at end of file |
