diff options
72 files changed, 1162 insertions, 169 deletions
@@ -0,0 +1,34 @@ +StylesPath = ci/vale +MinAlertLevel = suggestion + +[*.rst] +BasedOnStyles = VyOS + +Google.DateFormat = YES +vale.GenderBias = NO +vale.Hedging = NO +vale.Redundancy = NO +vale.Repetition = YES +vale.Uncomparables = NO +proselint.GenderBias = YES + +# Custom block scoping (see the regex101 links for unit tests): +# +# Rule #1 (https://regex101.com/r/TJQLJ4/2/tests): Ignore `{%comment%}` blocks. This +# keeps Vale from flagging 'endcomment' as a spelling mistake. +# +# Rule #2 (https://regex101.com/r/7VA2lV/2/tests): Ignore `<div>`s and `<section>`s +# that specify `markdown="1"` since it isn't supported by Vale's Markdown +# parser (https://github.com/russross/blackfriday/issues/184). +# +# Rule #3 (https://regex101.com/r/NxFflU/1/tests): Ignore `{% include %}`-codeblock +# pairs. +BlockIgnores = (?s)({%\s?comment\s?%}.+?{%\s?endcomment\s?%}), \ +(?s)(<(?:div|section)[^>]*markdown="1"[^>]*>.*?</(?:div|section)>), \ +(?s)((?: *{% include [^%]+ %}\n)? *~~~.*?~~~~?) + +# Custom inline scoping (see the regex101 links for unit tests): +# +# Rule #1 (https://regex101.com/r/cTiITH/2/tests): Ignore `{% include %}`s, which +# contain file paths. +TokenIgnores = ({%\s?include\s? {{ [^}]+ }}[^%]+\s?%}) @@ -58,3 +58,17 @@ docker run --rm -it -v "$(pwd):/vyos" -w /vyos/docs vyos-docu make html docker run --rm -it -p 8000:8000 -v "$(pwd):/vyos" -w /vyos/docs vyos-docu make livehtml ``` +### Test the docs + +discuss in this Task: [T1731](https://phabricator.vyos.net/T1731) + +to test all files: + +```bash +$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos-docu vale . +``` + +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) -e GOSU_GID=$(id -g) vyos-docu vale clustering.rst +``` diff --git a/ci/vale/Google/AMPM.yml b/ci/vale/Google/AMPM.yml new file mode 100644 index 00000000..fbdc6e4f --- /dev/null +++ b/ci/vale/Google/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'AM' or 'PM' (preceded by a space)." +link: 'https://developers.google.com/style/word-list' +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M' + - '\d{1,2} ?[ap]m' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/ci/vale/Google/Acronyms.yml b/ci/vale/Google/Acronyms.yml new file mode 100644 index 00000000..f41af018 --- /dev/null +++ b/ci/vale/Google/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "Spell out '%s', if it's unfamiliar to the audience." +link: 'https://developers.google.com/style/abbreviations' +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/ci/vale/Google/Colons.yml b/ci/vale/Google/Colons.yml new file mode 100644 index 00000000..9a4b4b4a --- /dev/null +++ b/ci/vale/Google/Colons.yml @@ -0,0 +1,7 @@ +extends: existence +message: "'%s' should be in lowercase." +link: 'https://developers.google.com/style/colons' +nonword: true +level: warning +tokens: + - ':\s[A-Z]' diff --git a/ci/vale/Google/Contractions.yml b/ci/vale/Google/Contractions.yml new file mode 100644 index 00000000..905a39f4 --- /dev/null +++ b/ci/vale/Google/Contractions.yml @@ -0,0 +1,28 @@ +extends: substitution +message: "Feel free to use '%s' instead of '%s'." +link: 'https://developers.google.com/style/contractions' +level: suggestion +ignorecase: true +swap: + are not: aren't + cannot: can't + could not: couldn't + did not: didn't + do not: don't + does not: doesn't + has not: hasn't + have not: haven't + how is: how's + is not: isn't + it is: it's + should not: shouldn't + that is: that's + they are: they're + was not: wasn't + we are: we're + we have: we've + were not: weren't + what is: what's + when is: when's + where is: where's + will not: won't diff --git a/ci/vale/Google/DateFormat.yml b/ci/vale/Google/DateFormat.yml new file mode 100644 index 00000000..e9d227fa --- /dev/null +++ b/ci/vale/Google/DateFormat.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'July 31, 2016' format, not '%s'." +link: 'https://developers.google.com/style/dates-times' +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}' + - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}' diff --git a/ci/vale/Google/Ellipses.yml b/ci/vale/Google/Ellipses.yml new file mode 100644 index 00000000..436e6177 --- /dev/null +++ b/ci/vale/Google/Ellipses.yml @@ -0,0 +1,7 @@ +extends: existence +message: "In general, don't use an ellipsis." +link: 'https://developers.google.com/style/ellipses' +nonword: true +level: warning +tokens: + - '\.\.\.' diff --git a/ci/vale/Google/EmDash.yml b/ci/vale/Google/EmDash.yml new file mode 100644 index 00000000..c6018db1 --- /dev/null +++ b/ci/vale/Google/EmDash.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't put a space before or after an em dash." +link: 'https://developers.google.com/style/dashes' +nonword: true +level: error +tokens: + - '\s—' + - '—\s' diff --git a/ci/vale/Google/EnDash.yml b/ci/vale/Google/EnDash.yml new file mode 100644 index 00000000..194876aa --- /dev/null +++ b/ci/vale/Google/EnDash.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use an em dash ('—') instead of '–'." +link: 'https://developers.google.com/style/dashes' +nonword: true +level: error +tokens: + - '–' diff --git a/ci/vale/Google/Exclamation.yml b/ci/vale/Google/Exclamation.yml new file mode 100644 index 00000000..c4db380b --- /dev/null +++ b/ci/vale/Google/Exclamation.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't use exclamation points in text." +link: 'https://developers.google.com/style/exclamation-points' +nonword: true +level: error +tokens: + - '!' diff --git a/ci/vale/Google/FirstPerson.yml b/ci/vale/Google/FirstPerson.yml new file mode 100644 index 00000000..d2290611 --- /dev/null +++ b/ci/vale/Google/FirstPerson.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid first-person pronouns such as '%s'." +link: 'https://developers.google.com/style/pronouns#personal-pronouns' +ignorecase: true +level: warning +nonword: true +tokens: + - (?:^|\s)I\s + - \bme\b + - \bus\b + - \bours\b diff --git a/ci/vale/Google/Gender.yml b/ci/vale/Google/Gender.yml new file mode 100644 index 00000000..c8486181 --- /dev/null +++ b/ci/vale/Google/Gender.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Don't use '%s' as a gender-neutral pronoun." +link: 'https://developers.google.com/style/pronouns#gender-neutral-pronouns' +level: error +ignorecase: true +tokens: + - he/she + - s/he + - \(s\)he diff --git a/ci/vale/Google/GenderBias.yml b/ci/vale/Google/GenderBias.yml new file mode 100644 index 00000000..261cfb66 --- /dev/null +++ b/ci/vale/Google/GenderBias.yml @@ -0,0 +1,45 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +link: 'https://developers.google.com/style/inclusive-documentation' +ignorecase: true +level: error +swap: + (?:alumna|alumnus): graduate + (?:alumnae|alumni): graduates + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + chair(?:m[ae]n|wom[ae]n): chair(s) + congress(?:m[ae]n|wom[ae]n): member(s) of congress + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + landlord: building manager + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + manpower: personnel + men and girls: men and women + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + steward(?:ess)?: flight attendant + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/ci/vale/Google/HeadingPunctuation.yml b/ci/vale/Google/HeadingPunctuation.yml new file mode 100644 index 00000000..5c39abbf --- /dev/null +++ b/ci/vale/Google/HeadingPunctuation.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't put a period at the end of a heading." +link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings' +nonword: true +level: warning +scope: heading +tokens: + - '[a-z0-9][.](?:\s|$)' diff --git a/ci/vale/Google/Headings.yml b/ci/vale/Google/Headings.yml new file mode 100644 index 00000000..5afb968d --- /dev/null +++ b/ci/vale/Google/Headings.yml @@ -0,0 +1,26 @@ +extends: capitalization +message: "'%s' should use sentence-style capitalization." +link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings' +level: warning +scope: heading +match: $sentence +exceptions: + - Azure + - CLI + - Code + - Cosmos + - Docker + - Emmet + - I + - Kubernetes + - Linux + - macOS + - Marketplace + - MongoDB + - REPL + - Studio + - TypeScript + - URLs + - Visual + - VS + - Windows diff --git a/ci/vale/Google/Hyphens.yml b/ci/vale/Google/Hyphens.yml new file mode 100644 index 00000000..f9779637 --- /dev/null +++ b/ci/vale/Google/Hyphens.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't place a space on either side of a hyphen (unless it's suspended)." +link: 'https://developers.google.com/style/hyphens' +level: warning +nonword: true +tokens: + - '\s-' + - '-\s' diff --git a/ci/vale/Google/Latin.yml b/ci/vale/Google/Latin.yml new file mode 100644 index 00000000..f032b349 --- /dev/null +++ b/ci/vale/Google/Latin.yml @@ -0,0 +1,9 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +link: 'https://developers.google.com/style/abbreviations' +ignorecase: true +level: error +nonword: true +swap: + '\b(?:eg|e\.g\.)[\s,]': for example + '\b(?:ie|i\.e\.)[\s,]': that is diff --git a/ci/vale/Google/LyHyphens.yml b/ci/vale/Google/LyHyphens.yml new file mode 100644 index 00000000..d5b6a942 --- /dev/null +++ b/ci/vale/Google/LyHyphens.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' doesn't need a hyphen." +link: 'https://developers.google.com/style/hyphens' +level: error +ignorecase: false +nonword: true +tokens: + - '\s[^\s-]+ly-' diff --git a/ci/vale/Google/OptionalPlurals.yml b/ci/vale/Google/OptionalPlurals.yml new file mode 100644 index 00000000..7058932f --- /dev/null +++ b/ci/vale/Google/OptionalPlurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't use plurals in parentheses such as in '%s'." +link: 'https://developers.google.com/style/plurals-parentheses' +level: error +nonword: true +tokens: + - '\b\w+\(s\)' diff --git a/ci/vale/Google/Ordinal.yml b/ci/vale/Google/Ordinal.yml new file mode 100644 index 00000000..8c429e0f --- /dev/null +++ b/ci/vale/Google/Ordinal.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Spell out all ordinal numbers ('%s') in text." +link: 'https://developers.google.com/style/numbers' +level: error +nonword: true +tokens: + - \d+(?:st|th|rd) diff --git a/ci/vale/Google/OxfordComma.yml b/ci/vale/Google/OxfordComma.yml new file mode 100644 index 00000000..98b07113 --- /dev/null +++ b/ci/vale/Google/OxfordComma.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +link: 'https://developers.google.com/style/commas' +scope: sentence +level: warning +tokens: + - '(?:[^,]+,){1,}\s\w+\sand' diff --git a/ci/vale/Google/Parens.yml b/ci/vale/Google/Parens.yml new file mode 100644 index 00000000..3b8711d0 --- /dev/null +++ b/ci/vale/Google/Parens.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use parentheses judiciously." +link: 'https://developers.google.com/style/parentheses' +nonword: true +level: suggestion +tokens: + - '\(.+\)' diff --git a/ci/vale/Google/Passive.yml b/ci/vale/Google/Passive.yml new file mode 100644 index 00000000..3265890e --- /dev/null +++ b/ci/vale/Google/Passive.yml @@ -0,0 +1,184 @@ +extends: existence +link: 'https://developers.google.com/style/voice' +message: "In general, use active voice instead of passive voice ('%s')." +ignorecase: true +level: suggestion +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' + - awoken + - beat + - become + - been + - begun + - bent + - beset + - bet + - bid + - bidden + - bitten + - bled + - blown + - born + - bought + - bound + - bred + - broadcast + - broken + - brought + - built + - burnt + - burst + - cast + - caught + - chosen + - clung + - come + - cost + - crept + - cut + - dealt + - dived + - done + - drawn + - dreamt + - driven + - drunk + - dug + - eaten + - fallen + - fed + - felt + - fit + - fled + - flown + - flung + - forbidden + - foregone + - forgiven + - forgotten + - forsaken + - fought + - found + - frozen + - given + - gone + - gotten + - ground + - grown + - heard + - held + - hidden + - hit + - hung + - hurt + - kept + - knelt + - knit + - known + - laid + - lain + - leapt + - learnt + - led + - left + - lent + - let + - lighted + - lost + - made + - meant + - met + - misspelt + - mistaken + - mown + - overcome + - overdone + - overtaken + - overthrown + - paid + - pled + - proven + - put + - quit + - read + - rid + - ridden + - risen + - run + - rung + - said + - sat + - sawn + - seen + - sent + - set + - sewn + - shaken + - shaven + - shed + - shod + - shone + - shorn + - shot + - shown + - shrunk + - shut + - slain + - slept + - slid + - slit + - slung + - smitten + - sold + - sought + - sown + - sped + - spent + - spilt + - spit + - split + - spoken + - spread + - sprung + - spun + - stolen + - stood + - stridden + - striven + - struck + - strung + - stuck + - stung + - stunk + - sung + - sunk + - swept + - swollen + - sworn + - swum + - swung + - taken + - taught + - thought + - thrived + - thrown + - thrust + - told + - torn + - trodden + - understood + - upheld + - upset + - wed + - wept + - withheld + - withstood + - woken + - won + - worn + - wound + - woven + - written + - wrung diff --git a/ci/vale/Google/Periods.yml b/ci/vale/Google/Periods.yml new file mode 100644 index 00000000..d24a6a6c --- /dev/null +++ b/ci/vale/Google/Periods.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't use periods with acronyms or initialisms such as '%s'." +link: 'https://developers.google.com/style/abbreviations' +level: error +nonword: true +tokens: + - '\b(?:[A-Z]\.){3,}' diff --git a/ci/vale/Google/Quotes.yml b/ci/vale/Google/Quotes.yml new file mode 100644 index 00000000..3cb6f1ab --- /dev/null +++ b/ci/vale/Google/Quotes.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Commas and periods go inside quotation marks." +link: 'https://developers.google.com/style/quotation-marks' +level: error +nonword: true +tokens: + - '"[^"]+"[.,?]' diff --git a/ci/vale/Google/Ranges.yml b/ci/vale/Google/Ranges.yml new file mode 100644 index 00000000..3ec045e7 --- /dev/null +++ b/ci/vale/Google/Ranges.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add words such as 'from' or 'between' to describe a range of numbers." +link: 'https://developers.google.com/style/hyphens' +nonword: true +level: warning +tokens: + - '(?:from|between)\s\d+\s?-\s?\d+' diff --git a/ci/vale/Google/Semicolons.yml b/ci/vale/Google/Semicolons.yml new file mode 100644 index 00000000..bb8b85b4 --- /dev/null +++ b/ci/vale/Google/Semicolons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use semicolons judiciously." +link: 'https://developers.google.com/style/semicolons' +nonword: true +scope: sentence +level: suggestion +tokens: + - ';' diff --git a/ci/vale/Google/Slang.yml b/ci/vale/Google/Slang.yml new file mode 100644 index 00000000..63f4c248 --- /dev/null +++ b/ci/vale/Google/Slang.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Don't use internet slang abbreviations such as '%s'." +link: 'https://developers.google.com/style/abbreviations' +ignorecase: true +level: error +tokens: + - 'tl;dr' + - ymmv + - rtfm + - imo + - fwiw diff --git a/ci/vale/Google/Spacing.yml b/ci/vale/Google/Spacing.yml new file mode 100644 index 00000000..5f209a9f --- /dev/null +++ b/ci/vale/Google/Spacing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should have one space." +link: 'https://developers.google.com/style/sentence-spacing' +level: error +nonword: true +tokens: + - '[.?!] {2,}[A-Z]' + - '[.?!][A-Z]' diff --git a/ci/vale/Google/Spelling.yml b/ci/vale/Google/Spelling.yml new file mode 100644 index 00000000..57acb884 --- /dev/null +++ b/ci/vale/Google/Spelling.yml @@ -0,0 +1,8 @@ +extends: existence +message: "In general, use American spelling instead of '%s'." +link: 'https://developers.google.com/style/spelling' +ignorecase: true +level: warning +tokens: + - '(?:\w+)nised?' + - '(?:\w+)logue' diff --git a/ci/vale/Google/Units.yml b/ci/vale/Google/Units.yml new file mode 100644 index 00000000..220de3e9 --- /dev/null +++ b/ci/vale/Google/Units.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Put a nonbreaking space between the number and the unit in '%s'." +link: 'https://developers.google.com/style/units-of-measure' +nonword: true +level: error +tokens: + - \d+(?:GB|TB|MB) diff --git a/ci/vale/Google/Will.yml b/ci/vale/Google/Will.yml new file mode 100644 index 00000000..128a9183 --- /dev/null +++ b/ci/vale/Google/Will.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Avoid using '%s'." +link: 'https://developers.google.com/style/tense' +ignorecase: true +level: warning +tokens: + - will diff --git a/ci/vale/Google/WordList.yml b/ci/vale/Google/WordList.yml new file mode 100644 index 00000000..d5d6bea5 --- /dev/null +++ b/ci/vale/Google/WordList.yml @@ -0,0 +1,79 @@ +extends: substitution +message: "Use %s instead of '%s'." +link: 'https://developers.google.com/style/word-list' +level: warning +ignorecase: false +swap: + '(?:API Console|dev|developer) key': "'API key'" + '(?:cell ?phone|smart ?phone)': "'phone' or 'mobile phone'" + '(?:dev|developer|APIs) console': "'API console'" + '(?:e-mail|Email|E-mail)': "'email'" + '(?:file ?path|path ?name)': "'path'" + '(?:kill|terminate)': "'stop', 'exit', 'cancel', or 'end'" + '(?:OAuth ?2|Oauth)': "'OAuth 2.0'" + '(?:ok|Okay)': "'OK' or 'okay'" + '(?:WiFi|wifi)': "'Wi-Fi'" + '[\.]+apk': "'APK'" + '3\-D': "'3D'" + 'Google (?:I\-O|IO)': "'Google I/O'" + 'tap (?:&|and) hold': "'touch & hold'" + 'un(?:check|select)': "'clear'" + abort: "'stop', 'exit', 'cancel' or 'end'" + above: "'preceding'" + account name: "'username'" + action bar: "'app bar'" + admin: "'administrator'" + Ajax: "'AJAX'" + Android device: "'Android-powered device'" + android: "'Android'" + API explorer: "'APIs Explorer'" + application: "'app'" + approx\.: "'approximately'" + authN: "'authentication'" + authZ: "'authorization'" + autoupdate: "'automatically update'" + cellular data: "'mobile data'" + cellular network: "'mobile network'" + chapter: "'documents', 'pages', 'sections'" + check box: "'checkbox'" + check: "'select'" + CLI: "'command-line tool'" + click on: "'click' or 'click in'" + Cloud: "'Google Cloud Platform' or 'GCP'" + Container Engine: "'Kubernetes Engine'" + content type: "'media type'" + curated roles: "'predefined roles'" + data are: "'data is'" + Developers Console: "'Google API Console' or 'API Console'" + disabled?: "'turn off' or 'off'" + ephemeral IP address: "'ephemeral external IP address'" + fewer data: "'less data'" + file name: "'filename'" + firewalls: "'firewall rules'" + functionality: "'capability' or 'feature'" + Google account: "'Google Account'" + Google accounts: "'Google Accounts'" + Googling: "'search with Google'" + grayed-out: "'unavailable'" + HTTPs: "'HTTPS'" + in order to: "'to'" + ingest: "'import' or 'load'" + k8s: "'Kubernetes'" + long press: "'touch & hold'" + network IP address: "'internal IP address'" + omnibox: "'address bar'" + open-source: "'open source'" + overview screen: "'recents screen'" + regex: "'regular expression'" + SHA1: "'SHA-1' or 'HAS-SHA1'" + sign into: "'sign in to'" + sign-?on: "'single sign-on'" + static IP address: "'static external IP address'" + stylesheet: "'style sheet'" + synch: "'sync'" + tablename: "'table name'" + tablet: "'device'" + touch: "'tap'" + url: "'URL'" + vs\.: "'versus'" + World Wide Web: "'web'" diff --git a/ci/vale/Google/meta.json b/ci/vale/Google/meta.json new file mode 100644 index 00000000..3ae5fb21 --- /dev/null +++ b/ci/vale/Google/meta.json @@ -0,0 +1,16 @@ +{ + "author": "Joseph Kato", + "description": "A Vale-compatible implementation of the Microsoft Writing Style Guide.", + "email": "support@errata.ai", + "lang": "en", + "url": "https://github.com/errata-ai/Google/releases/latest/download/Google.zip", + "feed": "https://github.com/errata-ai/Google/releases.atom", + "issues": "https://github.com/errata-ai/Google/issues/new", + "license": "MIT", + "name": "Google", + "sources": [ + "https://developers.google.com/style/" + ], + "vale_version": ">=1.0.0", + "coverage": 0.0 +} diff --git a/ci/vale/Google/vocab.txt b/ci/vale/Google/vocab.txt new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/ci/vale/Google/vocab.txt diff --git a/ci/vale/VyOS/Terminology.yml b/ci/vale/VyOS/Terminology.yml new file mode 100644 index 00000000..57c1e6d6 --- /dev/null +++ b/ci/vale/VyOS/Terminology.yml @@ -0,0 +1,9 @@ +extends: substitution +message: Prefer '%s' over '%s' +ignorecase: false +level: warning +swap: + vyos: VyOS + Vyos: VyOS + VYOS: VyOS + Gre: GRE
\ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile index 7cd7c2e9..89f77125 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -23,7 +23,8 @@ RUN apt-get update && apt-get install -y \ texlive-fonts-recommended \ texlive-latex-extra \ sudo \ - gosu + gosu \ + curl RUN pip3 install sphinx-autobuild @@ -36,6 +37,11 @@ EXPOSE 8000 RUN sed "s/^%sudo.*/%sudo\tALL=(ALL) NOPASSWD:ALL/g" -i /etc/sudoers && \ chmod a+s /usr/sbin/useradd /usr/sbin/groupadd /usr/sbin/gosu /usr/sbin/usermod +# vale +RUN curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v1.7.1 + + + COPY entrypoint.sh /usr/local/bin/entrypoint.sh ENTRYPOINT ["/usr/local/bin/entrypoint.sh"] diff --git a/docs/_static/images/vyos-downloads.png b/docs/_static/images/vyos-downloads.png Binary files differnew file mode 100644 index 00000000..6bad2b19 --- /dev/null +++ b/docs/_static/images/vyos-downloads.png diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/appendix/migrate-from-vyatta.rst index b7747605..39b5939b 100644 --- a/docs/appendix/migrate-from-vyatta.rst +++ b/docs/appendix/migrate-from-vyatta.rst @@ -27,7 +27,7 @@ public key. .. code-block:: sh - vyatta@vyatta:~$ '''wget http://vyos.net/so3group_maintainers.key''' + vyatta@vyatta:~$ '''wget http://wiki.vyos.net/so3group_maintainers.key''' Connecting to vyos.net (x.x.x.x:80) so3group_maintainers 100% |******************************| 3125 --:--:-- ETA vyatta@vyatta:~$ '''sudo apt-key add so3group_maintainers.key''' diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 325c629a..3d5814e4 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -30,7 +30,7 @@ the following optional parts will be required: Latest VyOS rolling releases boot without any problem on this board. You also receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no information -about [OpenBMC](https://www.openbmc.org/)) so far on this motherboard. +about `OpenBMC <https://www.openbmc.org/>`_ so far on this motherboard). Pictures -------- @@ -94,10 +94,13 @@ Shopping Cart * 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM * 1x Kingston SUV500MS/120G -* 1x VARIA Group Item 326745 10" dual rack rack for APU4 +* 1x VARIA Group Item 326745 19" dual rack rack for APU4 +* 1x Compex WLE900VX (Optional mini PCIe WiFi module) -The 19" enclosure can accomodate two APU4 boards - there is a single and dual -cover. +The 19" enclosure can accomodate up to two APU4 boards - there is a single and +dual front cover. + +.. note:: Compex WLE900VX is only supported in mPCIe slot 1. VyOS 1.2 (crux) --------------- @@ -162,7 +165,7 @@ emulator to 9600 8N1 and after a while your console will show: You can now proceed with a regular image installation as described in :ref:`installation`. -^As the APU board itself still used a serial setting of 115200 8N1 it is strongly +As the APU board itself still used a serial setting of 115200 8N1 it is strongly recommended that you change the VyOS serial interface settings after your first successful boot. @@ -365,13 +368,13 @@ Reboot into BIOS, Chipset > South Bridge > USB Configuration: Install VyOS: ------------- -Create a VyOS bootable USB key. I Used the 64bits iso (VyOS 1.1.7) and live USB -installer (http://www.linuxliveusb.com/) +Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and `LinuxLive +USB Creator <http://www.linuxliveusb.com/>`_. I'm not sure if it helps the process but I changed default option to live-serial (line “default xxxx”) on the USB key under syslinux/syslinux.cfg. I connected the key to one black USB port on the back and powered on. The first -VyOS screen has some readability issues. Press enter to continue. +VyOS screen has some readability issues. Press :kbd:`Enter` to continue. Then VyOS should boot and you can perform the ``install image`` diff --git a/docs/build-vyos.rst b/docs/build-vyos.rst index 2ea2c217..bcd32ecb 100644 --- a/docs/build-vyos.rst +++ b/docs/build-vyos.rst @@ -13,7 +13,7 @@ Docker and works best on a fresh installation of Debain 8 (Jessie). the community. Since the source code is still public you can build your own ISO using the process described here. -Installing Docker and it's prequisites +Installing Docker and it's prerequisites .. code-block:: sh diff --git a/docs/clustering.rst b/docs/clustering.rst index 74cfcf42..d51f0073 100644 --- a/docs/clustering.rst +++ b/docs/clustering.rst @@ -3,7 +3,7 @@ Clustering ========== -The cluster feature allows 2 vyos routers to share IP adresses and various services. +The cluster feature allows 2 vyos routers to share IP addresses and various services. VyOS supports multicast clustering. diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 5bd80028..7d0e8767 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -105,7 +105,7 @@ The working configuration is the configuration which is currently being modified Saved configuration ^^^^^^^^^^^^^^^^^^^ -A saved configuration is a configuration saved to a file using the `save` command. It allowes 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.boot. +A saved configuration is a configuration saved to a file using the `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.boot. Navigating in Configuration Mode @@ -206,7 +206,7 @@ Managing the configuration -------------------------- The configuration is managed by the use of `set` and `delete` commands from within configuration mode. -Configuration commands are flattend from the tree into 'one-liner' commands shown in `show configuration commands` from operation mode. +Configuration commands are flattened from the tree into 'one-liner' commands shown in `show configuration commands` from operation mode. These commands are also relative to the level where they are executed and all redundant information from the current level is removed from the command entered. @@ -221,7 +221,7 @@ These commands are also relative to the level where they are executed and all re These two commands above are essentially the same, just executed from different levels in the hierarchy. To delete a configuration entry use the `delete` command, this also deletes all sub-levels under the current level you've specified in the `delete` command. -Deleting an entry could also mean to reset it back to its default value if the element is mandatory, in each case it will be removed from the configuration file. +Deleting an entry will also result in the element reverting back to its default value if one exists. .. code-block:: sh @@ -265,51 +265,7 @@ used. exit vyos@vyos:~$ -VyOS automatically maintains backups of previous configurations. To compare -configuration revisions in configuration mode, use the compare command: -.. code-block:: sh - - 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 - - [edit] - vyos@vyos# - -You can rollback configuration using the rollback command. This -command will apply the selected revision and trigger a system reboot. - -.. code-block:: sh - - 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! - [edit] - vyos@vyos# - -VyOS also supports saving and loading configuration remotely using SCP, FTP, -or TFTP. .. code-block:: sh @@ -332,6 +288,7 @@ When inside configuration mode you are not directly able to execute operational 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:: sh @@ -347,12 +304,10 @@ Command completion and syntax help with `?` and `[tab]` will also work. Configuration archive --------------------- -VyOS has built-in config archiving and versioning that renders tools like rancid, largely unnecessary. - -This feature was available in Vyatta Core since 6.3 +VyOS automatically maintains backups of previous configurations. Local archive and revisions ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Revisions are stored on disk. You can view them, compare them, and rollback to previous revisions if anything goes wrong. @@ -370,7 +325,36 @@ To view existing revisions, use `show system commit` operational mode command. 6 2015-03-25 00:16:47 by vyos via cli 7 2015-03-24 23:43:45 by root via boot-config-loader -You can compare revisions with `compare X Y` command, where X and Y are revision numbers. The output will describe how the configuration X is when comparted to Y, indicating with a plus sign (**+**) the additional parts X has when compared to y, and indicating with a minus sign (**-**) the lacking parts x misses when compared to y. +To compare configuration revisions in configuration mode, use the compare command: + +.. code-block:: sh + + 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 + + [edit] + vyos@vyos# + +Comparing Revisions +""""""""""""""""""" + +You can compare revisions with `compare X Y` command, where X and Y are revision numbers. The output will describe how the configuration X is when compared to Y, indicating with a plus sign (**+**) the additional parts X has when compared to y, and indicating with a minus sign (**-**) the lacking parts x misses when compared to y. .. code-block:: sh @@ -387,16 +371,32 @@ You can compare revisions with `compare X Y` command, where X and Y are revision - address 192.0.2.4/24 -} +Rolling Back Changes +"""""""""""""""""""" + +You can rollback configuration using the rollback command. This +command will apply the selected revision and trigger a system reboot. + +.. code-block:: sh -You can rollback to a previous revision with `rollback X`, where X is a revision number. Your system will reboot and load the config from the archive. + 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! + [edit] + vyos@vyos# Configuring the archive size ----------------------------- +"""""""""""""""""""""""""""" You can specify the number of revisions stored on disk with `set system config-management commit-revisions X`, where X is a number between 0 and 65535. When the number of revisions exceeds that number, the oldest revision is removed. Remote archive --------------- +^^^^^^^^^^^^^^ VyOS can copy the config to a remote location after each commit. TFTP, FTP, and SFTP servers are supported. diff --git a/docs/contributing/coding_guidelines.rst b/docs/contributing/coding_guidelines.rst index ff863d61..9c996518 100644 --- a/docs/contributing/coding_guidelines.rst +++ b/docs/contributing/coding_guidelines.rst @@ -54,7 +54,7 @@ The **get_config()** function must convert the VyOS config to an abstract intern representation. No other function is allowed to call ``vyos.config.Config`` object methods directly. The rationale for it is that when config reads are mixed with other logic, it's very hard to change the config syntax since you need to weed -out every occurence of the old syntax. If syntax-specific code is confined to a +out every occurrence of the old syntax. If syntax-specific code is confined to a single function, the rest of the code can be left untouched as long as the internal representation remains compatible. @@ -75,7 +75,7 @@ The **apply()** function applies the generated configuration to the live system. It should use non-disruptive reload whenever possible. It may execute disruptive operations such as daemon process restart if a particular component does not support non-disruptive reload, or when the expected service degradation is minimal -(for example, in case of auxillary services such as LLDPd). In case of high impact +(for example, in case of auxiliary services such as LLDPd). In case of high impact services such as VPN daemon and routing protocols, when non-disruptive reload is supported for some but not all types of configuration changes, scripts authors should make effort to determine if a configuration change can be done in a diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 4b762051..9e99ece8 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -31,7 +31,7 @@ This information is used in two ways: * Keep track of the progress (what we've already done in this branch and what we still need to do). * Prepare release notes. -To make this approach work, every change must be associated with a bug number and componant. +To make this approach work, every change must be associated with a bug number and component. If there is no bug/enhancement request for the changes you are going to make, you must create a `bugtracker`_ entry first. Once there is a `bugtracker`_ entry about it, you should reference in your commit message, as in: diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst index f539efda..49f9a230 100644 --- a/docs/contributing/vyos_cli.rst +++ b/docs/contributing/vyos_cli.rst @@ -5,8 +5,8 @@ VyOS CLI The bash completion in VyOS is defined in *templates*. Templates are text files stored in a directory tree, where directory names define command names, and -template files define command behaviour. Befor VyOS 1.2.x this files were created -by hand. After a complex redesing process_ the new style template are in XML. +template files define command behaviour. Before VyOS 1.2.x this files were created +by hand. After a complex redesign process_ the new style template are in XML. XML interface definitions for VyOS come with a RelaxNG schema and are located in the vyos-1x_ module. This schema is a slightly modified schema from VyConf_ diff --git a/docs/firewall.rst b/docs/firewall.rst index f875ad12..f4708b2a 100644 --- a/docs/firewall.rst +++ b/docs/firewall.rst @@ -37,7 +37,7 @@ or the need to reload individual firewall rules. .. note:: Groups can also be referenced by NAT configuration. -While network groups accept IP networks in CIDR notation, specific IP addresses +While **network groups** accept IP networks in CIDR notation, specific IP addresses can be added as a 32-bit prefix. If you foresee the need to add a mix of addresses and networks, the network group is recommended. @@ -49,7 +49,15 @@ internal network: set firewall group network-group NET-INSIDE network 192.168.0.0/24 set firewall group network-group NET-INSIDE network 192.168.1.0/24 -A port group represents only port numbers, not the protocol. Port groups can +Groups need to have unique names. Even though some contain IPv4 addresses and others contain IPv6 addresses, they still need to have unique names, so you may want to append "-v4" or "-v6" to your group names. + +.. code-block:: sh + + set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 + set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 + + +A **port group** represents only port numbers, not the protocol. Port groups can be referenced for either TCP or UDP. It is recommended that TCP and UDP groups are created separately to avoid accidentally filtering unnecessary ports. Ranges of ports can be specified by using `-`. diff --git a/docs/high-availability.rst b/docs/high-availability.rst index 9f4dd35d..07818e92 100644 --- a/docs/high-availability.rst +++ b/docs/high-availability.rst @@ -61,12 +61,50 @@ VRRP priority can be set with ``priority`` option: set high-availability vrrp group Foo priority 200 -The priority must be an interger 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 +----------- + +A sync group allows VRRP groups to transition together. + +.. code-block:: sh + + edit high-availability + set sync-group MAIN member VLAN9 + set sync-group MAIN member VLAN20 + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +.. code-block:: sh + + vrrp { + group VLAN9 { + interface eth0.9 + virtual-address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + virtual-address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } + } + + +.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. + Preemption ---------- -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indenfinitely. +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: diff --git a/docs/history.rst b/docs/history.rst index aa9bae7e..957cc6f3 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -15,28 +15,31 @@ edition of Vyatta. Here everyone loves learning, older managers and new users. VyOS is primarily based on `Debian GNU/Linux <http://www.debian.org/>`_ and the `Quagga <http://www.nongnu.org/quagga/>`_ routing engine. Its configuration syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the -`XORP project <http://www.xorp.org/>`_ (which was the original routing engine -Vyatta was based upon). +`XORP project <http://www.xorp.org/>`_, which was the original routing engine for +Vyatta. -Vyatta changed to the Quagga routing engine for release 4.0. +In the 4.0 release of Vyatta, the routing engine was changed to Quagga. -VyOS changed the routing engine to `FRRouting <https://frrouting.org/>`_ in -version 1.2.0 +As of version 1.2.0, VyOS now uses `FRRouting <https://frrouting.org/>`_ as +the routing engine. -**How it's different from other router distros?** +**How it's different from other router distributions and platforms?** +- More than just a firewall and VPN, VyOS includes extended routing capabilities like OSPFv2, OSPFv3, BGP, + VRRP, and extensive route policy mapping and filtering. - Unified command line interface in the style of hardware routers. -- Scriptable CLI +- Scriptable CLI. - Stateful configuration system: prepare changes and commit at once or discard, view previous revisions or rollback to them, archive revisions to remote - server, execute hooks at commit time... + server and execute hooks at commit time. - Image-based upgrade: keep multiple versions on the same system and revert to - previous image if something went wrong. -- Not just firewall and VPN: includes routing protocols such as BGP and OSPF and - complex routing policy language. + previous image if a problem arises. +- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard (in 1.2.0+), DPMVPN, and more. +- IPv4 and IPv6 support. - Runs on physical and virtual platforms alike: small x86 boards, big servers, - KVM, Xen, VMWare, Hyper-V... + KVM, Xen, VMWare, Hyper-V, and more. - Completely free and open source, with documented internal APIs and build procedures. -- Community driven: patches are welcome, all code, bugs, and nightly builds are +- Community driven. Patches are welcome and all code, bugs, and nightly builds are public. + diff --git a/docs/install.rst b/docs/install.rst index ba311a41..14d36fd9 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -13,33 +13,55 @@ The recommended system requirements are 512 MiB RAM and 2 GiB storage. Getting the software --------------------- -Registered subscribers can download stable release (LTS) images. If you log into https://support.vyos.io/ as a registered subscriber, you will see the "Downloads" link there. +Registered subscribers +^^^^^^^^^^^^^^^^^^^^^^ + +A registered subscriber can log into https://support.vyos.io/ to have access to a variety of different downloads via the "Downloads" link. +These downloads include LTS releases and associated hot-fixes, early public access releases, pre-built VM images, as well as device specific installation ISOs. + +.. figure:: /_static/images/vyos-downloads.png + +Building from source +^^^^^^^^^^^^^^^^^^^^ + +Non-subscribers can get the LTS release by building it from source. The instructions for building from source can be found at: -Non-subscribers can get the LTS release by building it from source. Just follow the instructions in https://github.com/vyos/vyos-build -Everyone can dowload VyOS rolling images from https://downloads.vyos.io/ +Rolling releases +^^^^^^^^^^^^^^^^ + +Non-subscribers and subscribers can download bleeding-edge VyOS rolling images from: + +https://downloads.vyos.io/ + +The following link will always fetch the most updated AMD64 image of the current branch: + +https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso Preparing software verification ------------------------------- -This subsection and the following one applies to dowloaded LTS images, for other cases please jump to :ref:`Install`. +This subsection and the following one applies to downloaded LTS images, for other cases please jump to :ref:`Install`. + +LTS images are signed by VyOS lead package-maintainer private key. With the official public key, the authenticity of the package can be verified. -LTS images are signed by VyOS lead package-maintainer private key. If you have our public key, you will be able to verify the authenticity of the package. +First, install GPG or another OpenPGP implementation. +On most GNU+Linux distributions it is installed by default as package managers use it to verify package signatures. +If not pre-installed, it will need to be downloaded and installed. -First you need to install GPG or another OpenPGP implementation. -On most GNU+Linux distributions it is installed by default because package managers use it to verify package signatures. -On other systems you may need to find and install the package. +The offical VyOS public key can be retrieved in a number of ways. Skip to :ref:`gpg-verification` if the key is already present. -Then you need VyOS public key. If you already have it, you can jump to :ref:`gpg-verification`. If you don't have it yet, you can get it from a key server. +It can be retrieved directly from a key server: ``gpg --recv-keys FD220285A0FE6D7E`` -Or open your web browser, visit a key server and copy our public key from there: https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E +Or it can be accessed from a key server via a web browser: -Or from this block below. +https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E +Or from the following block: .. code-block:: sh @@ -98,13 +120,11 @@ Or from this block below. -----END PGP PUBLIC KEY BLOCK----- - -Then you can paste that text in a new file, and import the file into GPG: +The key is then pasted into a new text file and imported into GPG: ``gpg --import file_with_the_public_key`` - -You can now check your GPG software has our public key. +The import can be verified with: .. code-block:: sh @@ -121,11 +141,11 @@ You can now check your GPG software has our public key. GPG verification ---------------- -As you have our public key, you just need the signature of the software you want to verify. +With the public key imported, the signature for the desired image needs to be downloaded. -.. note:: **In order to get the signature, go to your web browser and append .asc to the URL of your dowloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. +.. note:: The signature can be downloaded by appending `.asc` to the URL of the downloaded VyOS image. That small *.asc* file is the signature for the associated image. -So finally you can verify the authenticity of your image. +Finally, verify the authencity of the downloaded image: .. code-block:: sh @@ -142,8 +162,9 @@ Install ------- -The VyOS ISO is a Live CD and will boot to a functional VyOS image. To login -to the system, use the default username ``vyos`` with password ``vyos``. +The VyOS ISO is a Live CD and will boot to a functional VyOS image. + +To login to the system, use the default username ``vyos`` with password ``vyos``. .. code-block:: sh @@ -160,20 +181,15 @@ to the system, use the default username ``vyos`` with password ``vyos``. Unlike general purpose Linux distributions, VyOS uses "image installation" that mimics the user experience of traditional hardware routers and allows -you to keep multiple VyOS versions on the same machine and switch to a previous -version if something breaks after upgrade. Every version is contained in its -own squashfs image that is mounted in a union filesystem together with a -directory for mutable data (configs etc.). +keeping multiple VyOS versions installed simultaneously. This makes it possible to switch to a previous +version if something breaks after an upgrade. -.. note:: Older versions used to support non-image installation (`install system` command). - Support for this is removed from VyOS 1.2 (crux) and newer releases +Every version is contained in its own squashfs image that is mounted in a union filesystem together with a +directory for mutable data such as configurations, keys, or custom scripts. - This installation method has been deprecated since the time image installation - was introduced (long before the fork), and does not provide any version - management capabilities. You **should not** use it for new installations - even if it's still available in new versions. You should not worry about - older systems installed that way though, they can be upgraded with ``add - system image``. +.. note:: Older versions used to support non-image installation (``install system`` command). + Support for this is removed from VyOS 1.2 (crux) and newer releases. Older releases can still be upgraded + via ``add system image <image_path>`` To install VyOS, run ``install image``. @@ -238,3 +254,134 @@ After the installation is complete, remove the Live CD and reboot the system: + +.. _PXE Install: + +PXE Install +----------- + +VyOS can also be installed through PXE. This is a more complex installation method which allows deploying VyOS through the network. + + +Requirements +^^^^^^^^^^^^ + +* **Clients** (where VyOS is to be installed) **with a PXE-enabled NIC** +* A **DHCP server** +* A **TFTP server** +* A **HTTP server** (this is optional but we will use it to speed up our intallation) +* The **VyOS ISO** image to be installed (Do not use images prior to 1.2.3) +* The **pxelinux.0** and **ldlinux.c32** `files from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ + +Step 1: DHCP +^^^^^^^^^^^^ + +Configure a DHCP server so that it gives the client + + - An **IP address** + - The **TFTP server address** (DHCP option 66). Sometimes named *Boot server* + - The **bootfile name** (DHCP option 67), which is **pxelinux.0** + +In this example we configured an existent VyOS as the DHCP server: + +.. code-block:: sh + + vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } + [edit] + vyos@vyos# + + +.. _tftp-server: + +Step 2: TFTP +^^^^^^^^^^^^ + +Configure a TFTP server so that it serves the following: + + + The file **pxelinux.0** from the *Syslinux* distribution + + The file **ldlinux.c32** 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 <https://wiki.syslinux.org/wiki/index.php?title=Config>`_ shown below, which we named `default <https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration>`_. + + +In the example we configured our existent VyOS as the TFTP server too: + +.. code-block:: sh + + vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 + [edit] + vyos@vyos# + + +Example of the contents of the TFTP server: + +.. code-block:: sh + + vyos@vyos# ls -hal /config/tftpboot/ + total 29M + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . + drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. + -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos + -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 + -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg + -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + [edit] + vyos@vyos# + [edit] + vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg + total 12K + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. + -rw-r--r-- 1 root root 191 Oct 14 01:10 default + [edit] + vyos@vyos# + + +Example of simple (no menu) configuration file: + +.. code-block:: sh + + vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default + DEFAULT VyOS123 + + LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://192.168.1.2:8000/filesystem.squashfs + [edit] + vyos@vyos# + + + +Step 3: HTTP +^^^^^^^^^^^^ + + a) 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 its transfer. **Run a web server** --you can use a simple one like `Python's SimpleHTTPServer <https://docs.python.org/2/library/simplehttpserver.html>`_-- **and start serving the filesystem.squashfs file**. The file can be found inside the *live* directory of the extracted contents of the ISO file. + + + b) Edit the configuration file at the :ref:`tftp-server` so that it shows the correct URL at *fetch=http://address_of_your_HTTP_server/filesystem.squashfs*. Then 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 server and HTTP server have the right permissions to be accessed from the booting clients. + + +Step 4: Boot the clients +^^^^^^^^^^^^^^^^^^^^^^^^ + +Turn on the 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 normal VyOS installation. diff --git a/docs/interfaces/bridging.rst b/docs/interfaces/bridging.rst index 7fb20e0a..0adc9263 100644 --- a/docs/interfaces/bridging.rst +++ b/docs/interfaces/bridging.rst @@ -10,8 +10,9 @@ we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge. .. code-block:: sh set interfaces bridge 'br100' - set interfaces ethernet eth1 vif 100 bridge-group bridge br100 - + set interfaces ethernet eth1 vif 100 + set interfaces bridge br100 member interface eth1.100 + Interfaces assigned to a bridge-group do not have address configuration. An IP address can be assigned to the bridge interface itself, however, like any normal interface. @@ -33,9 +34,6 @@ Example Result: ethernet eth1 { [...] vif 100 { - bridge-group { - bridge br100 - } } } diff --git a/docs/load-balancing.rst b/docs/load-balancing.rst index 0f598b6e..fe0084bf 100644 --- a/docs/load-balancing.rst +++ b/docs/load-balancing.rst @@ -19,9 +19,9 @@ lets assume we have two dhcp WAN interfaces and one LAN (eth2) set load-balancing wan interface-health eth0 nexthop 'dhcp' set load-balancing wan interface-health eth1 nexthop 'dhcp' - set load-balancing wan rule 0 inbound-interface 'eth2' - set load-balancing wan rule 0 interface eth0 - set load-balancing wan rule 0 interface eth1 + set load-balancing wan rule 1 inbound-interface 'eth2' + set load-balancing wan rule 1 interface eth0 + set load-balancing wan rule 1 interface eth1 Balancing Rules --------------- @@ -30,11 +30,11 @@ Interfaces, their weight and the type of traffic to be balanced are defined in n 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 0...4294967295: +Create a load balancing rule, rule can be a number between 1 and 9999: .. code-block:: sh - vyos@vyos# set load-balancing wan rule 0 + vyos@vyos# set load-balancing wan rule 1 Possible completions: description Description for this rule > destination Destination @@ -55,8 +55,8 @@ Per default outbound traffic is distributed randomly across available interfaces .. code-block:: sh - set load-balancing wan rule 0 interface eth0 weight 2 - set load-balancing wan rule 0 interface eth1 weight 1 + set load-balancing wan rule 1 interface eth0 weight 2 + set load-balancing wan rule 1 interface eth1 weight 1 66% traffic is routed to eth0 and eth1 get 33% of traffic. @@ -254,4 +254,4 @@ Restart .. code-block:: sh - restart wan-load-balance
\ No newline at end of file + restart wan-load-balance diff --git a/docs/qos.rst b/docs/qos.rst index d68919d7..adf59108 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -809,7 +809,7 @@ Available commands: :code:`set traffic-policy round-robin <policy name> default quantum <packets>` -* Define a maximum queue lenght for the default policy in packets: +* Define a maximum queue length for the default policy in packets: :code:`set traffic-policy round-robin <policy name> default queue-limit <limit>` @@ -926,7 +926,7 @@ different amounts of bandwidth to different traffic classes. In contrast to round robin, shaper limits bandwidth allocation by traffic class whereas round robin divides the total available bandwidth between classes. -Avialable commands: +Available commands: * Define a shaper policy: diff --git a/docs/quick-start.rst b/docs/quick-start.rst index ebe4d402..518e5d86 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -28,10 +28,8 @@ Enable SSH for remote management: set service ssh port '22' - - Configure DHCP Server and DNS -^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: sh diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst index 9409690a..7cec4b7c 100644 --- a/docs/routing/mss-clamp.rst +++ b/docs/routing/mss-clamp.rst @@ -7,7 +7,7 @@ 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` keywork: +Clamping can be disabled per interface using the `disable` keyword: .. code-block:: sh diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 0fc01f04..36162bbe 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -23,7 +23,7 @@ Interface Configuration .. code-block:: sh - set interface eth1 address 172.16.17.1/24 + set interface ethernet eth1 address 172.16.17.1/24 Multiple ranges can be defined and can contain holes. diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index 067dacaf..4aaf6919 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -28,6 +28,12 @@ Setting a forwarding DNS server for a specific domain: .. code-block:: sh set service dns forwarding domain example.com server 192.0.2.1 + +Set which networks or clients are allowed to query the DNS Server. Allow from all: + +.. code-block:: sh + + set service dns forwarding allow-from 0.0.0.0/0 Example 1 ^^^^^^^^^ @@ -44,6 +50,7 @@ Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example set service dns forwarding name-server 8.8.8.8 set service dns forwarding name-server 8.8.4.4 set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 Example 2 ^^^^^^^^^ @@ -62,3 +69,4 @@ The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 set service dns forwarding name-server 2001:4860:4860::8844 set service dns forwarding listen-address 2001:db8::1 set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 diff --git a/docs/services/index.rst b/docs/services/index.rst index 8f7553a8..3e81b7a9 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -5,7 +5,7 @@ Services ======== -This chapter descriptes the available system/network services provided by VyOS. +This chapter describes the available system/network services provided by VyOS. .. toctree:: :maxdepth: 1 diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index 6a3bee7b..37214506 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -92,6 +92,6 @@ Exemple: Troubleshooting ^^^^^^^^^^^^^^^ -Use operationnal command ``show log lldp`` to display logs. +Use operational command ``show log lldp`` to display logs. .. include:: references.rst diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst index 2acc93f1..03e14971 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/services/pppoe-server.rst @@ -41,12 +41,12 @@ Connections can be locally checked via the command Client IP address pools ======================= -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 defintion. +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 '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. -**Client IP address via IP range defintion** +**Client IP address via IP range definition** .. code-block:: sh @@ -116,7 +116,7 @@ If attribute Filter-Id redefined, replace it in radius coa request Automatic VLAN creation ======================= -VLAN's can be created by accel-ppp on the fly if via the use of the kernel module vlan_mon, which is monitoring incoming vlans and creates the neccessary VLAN if required and allowed. +VLAN's can be created by accel-ppp on the fly if via the use of the kernel module vlan_mon, which is monitoring incoming vlans and creates the necessary VLAN if required and allowed. VyOS supports the use of either VLAN ID's or entire ranges, both values can be defined at the same time for an interface. .. code-block:: sh @@ -127,7 +127,7 @@ VyOS supports the use of either VLAN ID's or entire ranges, both values can be d set service pppoe-server interface eth3 vlan-range 2000-3000 -The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not neccessary anymore, it will remove it again. +The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not necessary anymore, it will remove it again. diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst index 54e23c6b..351d3324 100644 --- a/docs/services/snmp.rst +++ b/docs/services/snmp.rst @@ -33,10 +33,8 @@ agent which reports information via SNMP to the manager. An SNMP-managed network consists of three key components: * Managed devices - -* Agent – software which runs on managed devices - -* Network management station (NMS) – software which runs on the manager +* Agent - software which runs on managed devices +* Network management station (NMS) - software which runs on the manager A managed device is a network node that implements an SNMP interface that allows unidirectional (read-only) or bidirectional (read and write) access to @@ -179,10 +177,12 @@ After commit the resulting configuration will look like: SNMP Extensions ^^^^^^^^^^^^^^^ -To extend SNMP agent functionality, custom scripts can be executed every time the agent is being called. -This can be achieved by using `arbitrary extension commands`_. -The first step is to create a functional script of course, then upload it to your VyOS instance via the command ``scp your_script.sh vyos@your_router:/config/user-data``. -Once the script is uploaded, it needs to be configured via the command below. +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using ``arbitrary extension +commands``_. The first step is to create a functional script of course, then +upload it to your VyOS instance via the command ``scp your_script.sh +vyos@your_router:/config/user-data``. Once the script is uploaded, it needs to +be configured via the command below. .. code-block:: sh @@ -191,7 +191,8 @@ Once the script is uploaded, it needs to be configured via the command below. commit -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. +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. .. code-block:: sh @@ -201,6 +202,29 @@ The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will c NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 +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. + +Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the +following content: + +.. code-block:: sh + <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> + </Configuration-Management> .. include:: references.rst diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index 4d96f8de..caa255ce 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -44,13 +44,13 @@ Options * Allow ``root`` login, this can be set to allow ``root`` logins on SSH connections, however it is not advisable to use this setting as this bears - serious security risks. The default system user posesses all required + serious security risks. The default system user possesses all required privileges. :code:`set service ssh allow-root` * Allowed ciphers - A number of allowed ciphers can be specified, use multiple - occurances to allow multiple ciphers. + occurrences to allow multiple ciphers. :code:`set service ssh ciphers <cipher>` @@ -70,7 +70,7 @@ Options * `cast128-cbc` * Disable password authentication - If SSH key authentication is set up, - password-based user authetication can be disabled. This hardens security! + password-based user authentication can be disabled. This hardens security! :code:`set service ssh disable-password-authentication` diff --git a/docs/services/sstp-server.rst b/docs/services/sstp-server.rst index 8ee8ef45..bed2e1a6 100644 --- a/docs/services/sstp-server.rst +++ b/docs/services/sstp-server.rst @@ -14,7 +14,7 @@ Configuration The `Secure Socket Tunneling Protocol`_ (SSTP), provides ppp via a SSL/TLS channel. Using publically signed certificates as well a by private PKI, is fully supported. -All certficates should be stored on VyOS under ``/config/user-data/sstp``. +All certificates should be stored on VyOS under ``/config/user-data/sstp``. Self Signed CA and server certificates @@ -62,6 +62,7 @@ Use <tab> to setup the ``set sstp-settings ssl-certs ...``, it automatically loo .. code-block:: sh + edit service sstp-server set authentication local-users username foo password 'bar' set authentication mode 'local' set network-settings client-ip-settings gateway-address '10.100.100.1' diff --git a/docs/system/index.rst b/docs/system/index.rst index cea729e3..4edfce48 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -11,12 +11,14 @@ should be ready for further configuration which is described in this chapter. :maxdepth: 2 :hidden: + config-management eventhandler flowaccounting host-information + login-users + ntp + proxy serialconsole - system-users syslog task-scheduler - config-management time-zone diff --git a/docs/system/system-users.rst b/docs/system/login-users.rst index a2e62024..f330183f 100644 --- a/docs/system/system-users.rst +++ b/docs/system/login-users.rst @@ -96,6 +96,10 @@ This configuration results in: secret s3cr3t0816 } +.. note:: If you wan't to have admin users to authenticate via RADIUS it is + essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without + the attribute you will only get regular, non privilegued, system users. + Source Address ************** diff --git a/docs/system/ntp.rst b/docs/system/ntp.rst new file mode 100644 index 00000000..ed2a0ecb --- /dev/null +++ b/docs/system/ntp.rst @@ -0,0 +1,19 @@ +.. _ntp: + +NTP +=== + +there are 3 default NTP server set. You are able to change them. + +.. code-block:: sh + + set system ntp server 0.pool.ntp.org + set system ntp server 1.pool.ntp.org + set system ntp server 2.pool.ntp.org + +To set up VyOS as an NTP responder, you must specify the listen address and optionally the permitted clients. + +.. code-block:: sh + + set system ntp listen-address 192.168.199.1 + set system ntp allow-clients address 192.168.199.0/24 diff --git a/docs/system/proxy.rst b/docs/system/proxy.rst new file mode 100644 index 00000000..4ff5717b --- /dev/null +++ b/docs/system/proxy.rst @@ -0,0 +1,28 @@ +.. _proxy: + +System Proxy +============ + +Some IT environments require the use of a proxy to connect to the Internet. +The option allowes to set a HTTP proxy and if necessary, supports `basic auth`_. + +The code example below sets a proxy for all HTTP, HTTPS and FTP (anonymous ftp) connections, initiated by vyos. + +.. code-block:: sh + + set system proxy url http://10.100.100.1 + set system proxy port 8080 + +That enables the update of a system image if the vyos system operates behind a proxy. + +.. code-block:: sh + + 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 + 1 413M 1 4479k 0 0 995k 0 0:07:04 0:00:04 0:07:00 995k + + + +.. _`basic auth`: https://tools.ietf.org/html/rfc7617 diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 9bab2b0c..055a2d5c 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -5,7 +5,7 @@ VPN === -This chapter descriptes the available VPN services provided by VyOS. +This chapter describes the available VPN services provided by VyOS. .. toctree:: :hidden: diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index e252d016..7e468c7b 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -160,7 +160,7 @@ OpenVPN Server Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. This guide assumes you have already setup a PKI and have a CA certificate, a server certificate and -key, a certificate revokation list, a Diffie-Hellman key exchange parameters +key, a certificate revocation list, a Diffie-Hellman 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 @@ -235,11 +235,11 @@ OpenLDAP ======== Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employes. VyOS and OpenVPN support using +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 -shiped with every VyOS installation. A dedicated configuration file is required. +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:: sh @@ -306,7 +306,7 @@ Despite the fact that AD is a superset of LDAP </Group> </Authorization> -If you only wan't to check if the user account is enabled and can authenticate +If you only want to check if the user account is enabled and can authenticate (against the primary group) the following snipped is sufficient: .. code-block:: sh diff --git a/docs/vpn/site2site_ipsec.rst b/docs/vpn/site2site_ipsec.rst index 41115f8c..ac410d52 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/vpn/site2site_ipsec.rst @@ -41,7 +41,7 @@ Each site-to-site peer has the next options: * ``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 revocated; + * ``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: diff --git a/docs/vpn/wireguard.rst b/docs/vpn/wireguard.rst index a2f45913..a9d27330 100644 --- a/docs/vpn/wireguard.rst +++ b/docs/vpn/wireguard.rst @@ -42,7 +42,7 @@ Named keypairs can be used on a interface basis, if configured. If multiple wireguard interfaces are being configured, each can have their own keypairs. -The commands below will generate 2 keypairs, which are not releated +The commands below will generate 2 keypairs, which are not related to each other. .. code-block:: sh @@ -79,6 +79,8 @@ below is always the public key from your peer, not your local one. set interfaces wireguard wg01 port '12345' set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 +.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior. + 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 defined and routed, the last check is allowed-ips which either prevents or allows the |
