From 371bf8185f3cd0628969a8603aa92503b2fc3853 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:08:35 +0100 Subject: rearange changelog, cli, contributing --- .gitignore | 3 + docs/about.rst | 27 -- docs/automation/index.rst | 9 + docs/changelog/1.2.1.rst | 52 ++++ docs/changelog/1.2.2.rst | 46 ++++ docs/changelog/1.2.3.rst | 62 +++++ docs/changelog/1.2.4.rst | 65 +++++ docs/changelog/1.2.5.rst | 60 +++++ docs/changelog/index.rst | 14 + docs/cli.rst | 10 +- docs/contributing/documentation.rst | 89 ++++++- docs/contributing/index.rst | 13 + docs/copyright.rst | 19 ++ docs/draw.io/pbr_example_1.drawio | 1 - docs/draw.io/vpn_s2s_ikev2.drawio | 1 - docs/history.rst | 47 ---- docs/index.rst | 108 ++------ docs/install.rst | 514 ------------------------------------ docs/installation/index.rst | 18 ++ docs/installation/install.rst | 514 ++++++++++++++++++++++++++++++++++++ docs/introducing/about.rst | 27 ++ docs/introducing/history.rst | 47 ++++ docs/introducing/releases.rst | 29 ++ docs/troubleshooting.rst | 446 ------------------------------- docs/troubleshooting/index.rst | 446 +++++++++++++++++++++++++++++++ 25 files changed, 1533 insertions(+), 1134 deletions(-) delete mode 100644 docs/about.rst create mode 100644 docs/automation/index.rst create mode 100644 docs/changelog/1.2.1.rst create mode 100644 docs/changelog/1.2.2.rst create mode 100644 docs/changelog/1.2.3.rst create mode 100644 docs/changelog/1.2.4.rst create mode 100644 docs/changelog/1.2.5.rst create mode 100644 docs/changelog/index.rst create mode 100644 docs/contributing/index.rst create mode 100644 docs/copyright.rst delete mode 100644 docs/draw.io/pbr_example_1.drawio delete mode 100644 docs/draw.io/vpn_s2s_ikev2.drawio delete mode 100644 docs/history.rst delete mode 100644 docs/install.rst create mode 100644 docs/installation/index.rst create mode 100644 docs/installation/install.rst create mode 100644 docs/introducing/about.rst create mode 100644 docs/introducing/history.rst create mode 100644 docs/introducing/releases.rst delete mode 100644 docs/troubleshooting.rst create mode 100644 docs/troubleshooting/index.rst diff --git a/.gitignore b/.gitignore index 06d7c4cd..27188bd2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# Sphinx +_build/ + # python virtualenv venv/ ENV/ diff --git a/docs/about.rst b/docs/about.rst deleted file mode 100644 index 383c95eb..00000000 --- a/docs/about.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _about: - -##### -About -##### - -VyOS is an open source network operating system based on Debian GNU/Linux. - -VyOS provides a free routing platform that competes directly with other -commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it can be used -as a router and firewall platform for cloud deployments. - -We use multiple live versions of our manual hosted thankfully by -https://readthedocs.org. We will provide one version of the manual for every -VyOS major version starting with VyOS 1.2 which will receive Long-term support -(LTS). - -The manual version is selected/specified by its Git branch name. You can -switch between versions of the documentation by selecting the appropriate -branch on the bottom left corner. - -VyOS CLI syntax may change between major (and sometimes minor) versions. Please -always refer to the documentation matching your current, running installation. -If a change in the CLI is required, VyOS will ship a so called migration script -which will take care of adjusting the syntax. No action needs to be taken by -you. diff --git a/docs/automation/index.rst b/docs/automation/index.rst new file mode 100644 index 00000000..a3df9bc0 --- /dev/null +++ b/docs/automation/index.rst @@ -0,0 +1,9 @@ +############### +VyOS Automation +############### + + + * Ansible + * Saltstack + * HTTP-API + * startup scripts \ No newline at end of file diff --git a/docs/changelog/1.2.1.rst b/docs/changelog/1.2.1.rst new file mode 100644 index 00000000..4f22dd0a --- /dev/null +++ b/docs/changelog/1.2.1.rst @@ -0,0 +1,52 @@ +1.2.1 +===== + +VyOS 1.2.1 is a maintenance release made in April 2019. + +Resolved issues +--------------- + +* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers +* :vytask:`T1326` The kernel now includes drivers for various USB serial + adapters, which allows people to add a serial console to a machine without + onboard RS232, or connect to something else from the router +* The collection of network card firmware is now much more extensive +* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC + addresses in the RFC-compliant mode +* :vytask:`T1330` DHCP WPAD URL option works correctly again +* :vytask:`T1312` Many to many NAT rules now can use source/destination and + translation networks of non-matching size. If 1:1 network bits translation is + desired, it's now users responsibility to check if prefix length matches. +* :vytask:`T1290` IPv6 network prefix translation is fixed +* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely + used in PPPoE passwords +* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends + with a leaf node such as ``timezone`` in ``show system | commands`` +* :vytask:`T1235` ``show | commands`` correctly works in config mode now +* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option +* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest + Crux +* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses + other than loopback was fixed +* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to + start is fixed +* :vytask:`T1067` VXLAN value validation is improved +* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS + forwarding +* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with + more than one upstream interface +* :vytask:`T1234` ``relay-agents-packets`` option works correctly now +* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change +* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name +* :vytask:`T1279` ACPI power off works again +* :vytask:`T1247` Negation in WAN load balancing rules works again +* :vytask:`T1218` FRR staticd now starts on boot correctly +* :vytask:`T1296` The installer now correctly detects SD card devices +* :vytask:`T1225` Wireguard peers can be disabled now +* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete + is fixed +* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration +* :vytask:`T1060` It's now possible to exclude hosts from the transparent + web proxy +* :vytask:`T484` An issue with rules impossible to delete from the zone-based + firewall is fixed \ No newline at end of file diff --git a/docs/changelog/1.2.2.rst b/docs/changelog/1.2.2.rst new file mode 100644 index 00000000..17ba941f --- /dev/null +++ b/docs/changelog/1.2.2.rst @@ -0,0 +1,46 @@ +1.2.2 +===== + +1.2.2 is a maintenance release made in July 2019. + +New features +------------ + +* Options for per-interface MSS clamping. +* BGP extended next-hop capability +* Relaxed BGP multipath option +* Internal and external options for "remote-as" (accept any AS as long as it's + the same to this router or different, respectively) +* "Unnumbered" (interface-based) BGP peers +* BGP no-prepend option +* Additive BGP community option +* OSPFv3 network type option +* Custom arguments for VRRP scripts +* A script for querying values from config files + +Resolved issues +--------------- + +* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability +* :vytask:`T1371` VRRP health-check scripts now can use arguments +* :vytask:`T1497` DNS server addresses coming from a DHCP server are now + correctly propagated to resolv.conf +* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used + for recursive queries +* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly +* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors +* :vytask:`T1458` Correct hostname is sent to remote syslog again +* :vytask:`T1438` Board serial number from DMI is correctly displayed in + ``show version`` +* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in + remote syslog config +* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` +* :vytask:`T1174` ``system domain-name`` is correctly included in + ``/etc/resolv.conf`` +* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` + settings +* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines +* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address +* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU +* :vytask:`T1505` vyos.config ``return_effective_values()`` function now + correctly returns a list rather than a string \ No newline at end of file diff --git a/docs/changelog/1.2.3.rst b/docs/changelog/1.2.3.rst new file mode 100644 index 00000000..653beec1 --- /dev/null +++ b/docs/changelog/1.2.3.rst @@ -0,0 +1,62 @@ +1.2.3 +===== + +1.2.3 is a maintenance and feature backport release made in September 2019. + +New features +------------ + +* HTTP API +* :vytask:`T1524` "set service dns forwarding allow-from " + option for limiting queries to specific client networks +* :vytask:`T1503` Functions for checking if a commit is in progress +* :vytask:`T1543` "set system contig-mangement commit-archive source-address" + option +* :vytask:`T1554` Intel NIC drivers now support receive side scaling and + multiqueue + +Resolved issues +--------------- + +* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit + errors +* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive + lookups on domain specific forwarders +* :vytask:`T1362` Special characters in VRRP passwords are handled correctly +* :vytask:`T1377` BGP weight is applied properly +* :vytask:`T1420` Fixed permission for log files +* :vytask:`T1425` Wireguard interfaces now support /31 addresses +* :vytask:`T1428` Wireguard correctly handles firewall marks +* :vytask:`T1439` DHCPv6 static mappings now work correctly +* :vytask:`T1450` Flood ping commands now works correctly +* :vytask:`T1460` Op mode "show firewall" commands now support counters longer + than 8 digits (T1460) +* :vytask:`T1465` Fixed priority inversion in VTI commands +* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option +* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC + compatibility mode enabled +* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings +* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces +* :vytask:`T1530` Fixed "set system syslog global archive file" command +* :vytask:`T1531` Multiple fixes in cluster configuration scripts +* :vytask:`T1537` Fixed missing help text for "service dns" +* :vytask:`T1541` Fixed input validation in DHCPv6 relay options +* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall + assigned to it in one commit +* :vytask:`T1559` URL filtering now uses correct rule database path and works + again +* :vytask:`T1579` "show log vpn ipsec" command works again +* :vytask:`T1576` "show arp interface " command works again +* :vytask:`T1605` Fixed regression in L2TP/IPsec server +* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +* :vytask:`T1616` "renew dhcpv6" command now works from op mode +* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works + correctly now +* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple + improvements in name servers and hosts configuration handling + +Internals +--------- + +``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the +*vyos-hostsd* service that listens on a ZMQ socket for update messages. \ No newline at end of file diff --git a/docs/changelog/1.2.4.rst b/docs/changelog/1.2.4.rst new file mode 100644 index 00000000..397c9bb9 --- /dev/null +++ b/docs/changelog/1.2.4.rst @@ -0,0 +1,65 @@ +1.2.4 +===== + +1.2.4 is a maintenance release made in December 2019. + +Resolved issues +--------------- + +* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 +* :vytask:`T818` SNMP v3 - remove required engineid from user node +* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) +* :vytask:`T1183` BFD Support via FRR +* :vytask:`T1299` Allow SNMPd to be extended with custom scripts +* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option +* :vytask:`T1391` In route-map set community additive +* :vytask:`T1394` syslog systemd and host_name.py race condition +* :vytask:`T1401` Copying files with the FTP protocol fails if the password contains special characters +* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes to fix +* :vytask:`T1430` Add options for custom DHCP client-id and hostname +* :vytask:`T1447` Python subprocess called without import in host_name.py +* :vytask:`T1470` improve output of "show dhcpv6 server leases" +* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf +* :vytask:`T1496` Separate rolling release and LTS kernel builds +* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting +* :vytask:`T1568` strip-private command improvement for additional masking of IPv6 and MAC address +* :vytask:`T1578` completion offers "show table", but show table does not exist +* :vytask:`T1593` Support ip6gre +* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" +* :vytask:`T1638` vyos-hostsd not setting system domain name +* :vytask:`T1678` hostfile-update missing line feed +* :vytask:`T1694` NTPd: Do not listen on all interfaces by default +* :vytask:`T1701` Delete domain-name and domain-search won't work +* :vytask:`T1705` High CPU usage by bgpd when snmp is active +* :vytask:`T1707` DHCP static mapping and exclude address not working +* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 +* :vytask:`T1709` Update WireGuard to 0.0.20190913 +* :vytask:`T1716` Update Intel NIC drivers to recent versions +* :vytask:`T1726` Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 +* :vytask:`T1728` Update Linux Kernel to 4.19.79 +* :vytask:`T1737` SNMP tab completion missing +* :vytask:`T1738` Copy SNMP configuration from node to node raises exception +* :vytask:`T1740` Broken OSPFv2 virtual-link authentication +* :vytask:`T1742` NHRP unable to commit. +* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must be greater or equal to the range start address y!" when static mapping has same IP as range stop +* :vytask:`T1749` numeric validator doesn't support multiple ranges +* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) +* :vytask:`T1772` constraints in XML are partially broken +* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR +* :vytask:`T1780` Adding ipsec ike closeaction +* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py implementation +* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation +* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 +* :vytask:`T1800` Update Linux Kernel to v4.19.84 +* :vytask:`T1809` Wireless: SSID scan does not work in AP mode +* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp +* :vytask:`T1812` DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling +* :vytask:`T1819` Reboot kills SNMPv3 configuration +* :vytask:`T1822` Priority inversion wireless interface dhcpv6 +* :vytask:`T1825` Improve DHCP configuration error message +* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails to create an xml +* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" +* :vytask:`T1841` PPP ipv6-up.d direcotry missing +* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface +* :vytask:`T1903` Implementation udev predefined interface naming +* :vytask:`T1904` update eth1 and eth2 link files for the vep4600 \ No newline at end of file diff --git a/docs/changelog/1.2.5.rst b/docs/changelog/1.2.5.rst new file mode 100644 index 00000000..231e92f2 --- /dev/null +++ b/docs/changelog/1.2.5.rst @@ -0,0 +1,60 @@ +1.2.5 +===== + +1.2.5 is a maintenance release made in April 2020. + +Resolved issues +--------------- + +* :vytask:`1020` OSPF Stops distributing default route after a while +* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) +* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. +* :vytask:`1341` Adding rate-limiter for pppoe server users +* :vytask:`1376` Incorrect DHCP lease counting +* :vytask:`1392` Large firewall rulesets cause the system to lose configuration and crash at startup +* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with each other +* :vytask:`1452` accel-pppoe - add vendor option to shaper +* :vytask:`1490` BGP configuration (is lost|not applied) when updating 1.1.8 -> 1.2.1 +* :vytask:`1780` Adding ipsec ike closeaction +* :vytask:`1803` Unbind NTP while it's not requested... +* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server +* :vytask:`1827` Increase default gc_thresh +* :vytask:`1828` Missing completion helper for "set system syslog host 192.0.2.1 facility all protocol" +* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to existing package +* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' +* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to destroy the running config. +* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address +* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s +* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and validators +* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at commit time +* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding stop-script +* :vytask:`1891` Router announcements broken on boot +* :vytask:`1900` Enable SNMP for VRRP. +* :vytask:`1902` Add redistribute non main table in bgp +* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks +* :vytask:`1913` "system ipv6 blacklist" command has no effect +* :vytask:`1914` IPv6 multipath hash policy does not apply +* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 +* :vytask:`1934` Change default hostname when deploy from OVA without params. +* :vytask:`1935` NIC identification and usage problem in Hyper-V environments +* :vytask:`1936` pppoe-server CLI control features +* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit fails +* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore +* :vytask:`1970` Correct adding interfaces on boot +* :vytask:`1971` Missing modules in initrd.img for PXE boot +* :vytask:`1998` Update FRR to 7.3 +* :vytask:`2001` Error when router reboot +* :vytask:`2032` Monitor bandwidth bits +* :vytask:`2059` Set source-validation on bond vif don't work +* :vytask:`2066` PPPoE interface can be created multiple times - last wins +* :vytask:`2069` PPPoE-client does not works with service-name option +* :vytask:`2077` ISO build from crux branch is failing +* :vytask:`2079` Update Linux Kernel to v4.19.106 +* :vytask:`2087` Add maxfail 0 option to pppoe configuration. +* :vytask:`2100` BGP route adverisement wih checks rib +* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers +* :vytask:`2197` Cant add vif-s interface into a bridge +* :vytask:`2228` WireGuard does not allow ports < 1024 to be used +* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' +* :vytask:`2272` Set system flow-accounting disable-imt has syntax error +* :vytask:`2276` PPPoE server vulnerability \ No newline at end of file diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst new file mode 100644 index 00000000..26262932 --- /dev/null +++ b/docs/changelog/index.rst @@ -0,0 +1,14 @@ +######### +Changelog +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + 1.2.5 + 1.2.4 + 1.2.3 + 1.2.2 + 1.2.1 diff --git a/docs/cli.rst b/docs/cli.rst index 4694cc5d..b138b18b 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,14 +1,14 @@ .. _cli: -### -CLI -### +##################### +Comand Line Interface +##################### The VyOS :abbr:`CLI (Command-Line Interface)` comprises an operational and a configuration mode. Operational Mode -================ +################ Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the @@ -73,7 +73,7 @@ When viewing in page mode the following commands are available: in the event that the output has lines which exceed the terminal size. Configuration Mode -================== +################## The list of all operational level commands is available at :ref:`configuration_level_commands`. diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index e8d1dba5..9dd0c495 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -1,7 +1,8 @@ .. _documentation: +############# Documentation -============= +############# As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be @@ -15,7 +16,7 @@ guide how to do so. documentation. Forking Workflow ----------------- +================ The Forking Workflow is fundamentally different than other popular Git workflows. Instead of using a single server-side repository to act as the @@ -102,17 +103,20 @@ access to the official codebase. push origin master`` Style Guide ------------ +=========== -Sections -^^^^^^^^ +Formating and Sphinxmarkup +-------------------------- + +TOC Level +^^^^^^^^^^ We use the following syntax for Headlines. .. code-block:: none ##### - Parts + Title ##### ******** @@ -159,16 +163,17 @@ render the documentation. cfgcmd """""" -When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. An explanation of the described command should be -added below this statement. +When documenting CLI commands use the ``.. cfgcmd::`` directive +for all configuration mode commands. An explanation of the described command +should be added below this statement. +Replace all variable contents with or somthing similar. With those custom commands it will be possible to render them in a more descriptive way in the resulting HTML/PDF manual. .. code-block:: none - .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + .. cfgcmd:: protocols static arp hwaddr This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. @@ -250,6 +255,70 @@ URL. This is heavily used in the :ref:`release-notes` section. * :vytask:`T1605` Fixed regression in L2TP/IPsec server * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +Page content +------------ + +The documentation have 3 different types of pages, the same kind of pages must +have the same structure to achieve a recognition factor. + +For all *.rst files must follow the same TOC Level syntax and have to start with + +.. code-block:: + + ##### + Titel + ##### + +Configuration mode pages +^^^^^^^^^^^^^^^^^^^^^^^^ + +A configuration mode article covers a specific level of a command. +The exact level depends on the command. + +For example: + + * ``set zone-policy`` is written in ``zone-policy/index.rst`` + * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst`` + +The article starts with a short intruducing about the command or the technologie. +Include some helpfull links or background informations. + +After this a optional section follows. Some commands have requirements like the +compatible hardware (e.g. Wifi) or some commands you have to set before. For +example it is recommended to set a route-map before configure bgp. + +In the configuration part of the page all possible confiuration options +should be documented. Use ``.. cfgcmd::`` like described above. + +Related Operation command must be documented in the next part of the articel. +Use ``::opcmd..`` for these commands. + +If there some troubleshooting guides releated to the commands. Explain it in the +next optional part. + +Examples: + + * ssh + + + +Operation mode pages +^^^^^^^^^^^^^^^^^^^^ + +Operation mode commands, which didn't fit in a related configuraton mode command +must documented in this part of the documentation. + +.. todo:: + + create structure + + +Anything else +^^^^^^^^^^^^^ + +Anything else what is not a configuration or a operation command have no +predefined structure. + .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..c3bb2688 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,13 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 2 + + build-vyos + debugging + development + documentation + issues-features + upstream-packages \ No newline at end of file diff --git a/docs/copyright.rst b/docs/copyright.rst new file mode 100644 index 00000000..beebc2a2 --- /dev/null +++ b/docs/copyright.rst @@ -0,0 +1,19 @@ +################ +Copyright Notice +################ + +Copyright (C) 2018-2020 VyOS maintainers and contributors + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on all +copies. + +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided that the entire resulting +derived work is distributed under the terms of a permission notice identical +to this one. + +Permission is granted to copy and distribute translations of this manual into +another language, under the above conditions for modified versions, except that +this permission notice may be stated in a translation approved by the VyOS +maintainers. \ No newline at end of file diff --git a/docs/draw.io/pbr_example_1.drawio b/docs/draw.io/pbr_example_1.drawio deleted file mode 100644 index 0d496572..00000000 --- a/docs/draw.io/pbr_example_1.drawio +++ /dev/null @@ -1 +0,0 @@ -7VrbcqM4EP0aP4ZCgLk8xkk8u1UzW97K7FyepmRQsGoEYoUc2/P1K4G4CLBNJo7j2rLzAGpJrVafPq2WnYl9l2w/MJitPtEIkYllRtuJfT+xLMtzTPGQkl0pCQKnFMQMR6UINIJH/AspoZoXr3GEcm0gp5RwnOnCkKYpCrkmg4zRjT7siRJ91QzGqCd4DCHpS7/iiK+UFJhm0/EHwvFKLe1PVccShj9jRtepWm9i2U/Fp+xOYKVLjc9XMKKblsh+mNh3jFJeviXbO0Skbyu3lfPme3pruxlK+ZgJn4MU/ArY39bX3eKfT37yffHh8w2wSzXPkKxRtQ+XCIWzCD9Lq/lOecr9dy1NnXG05TeQ4Did2LdiBEFPXDxET+H+lN/kBciyD9jZtpkp3mL1LFbIM5h2ZcuuQGoctGPUUn8+LkClSbimVKYvIMS9RYVsyDghLryiS9/HUa/zCwgswzSAMcI5YxxhaZZYK54Q8QZE3zNiHAu2fYRLRBY0xxxT4Y/7JeWcJmKActB9KMIYMSEgcuSsJtcdJZQVait6NUpv1VxOM+klzujPmsRWLWlpME3fnEsEnjAhQ5prkspBEcxXKFIN0ZPJ7SXbWCZCA9PcM7DISrkRErqOaj9I49B2L0lBTX2RUhFNEGc7MURNuAkCv5yj0qkTlM1NKzf5SrZqpSVgqbQLVT6Ma91NThAvKi28JEU4r04RrLDzgnOEdZwG58kRJ/bUKZKEZYzwzjVJnDNJeO6lJQnLHUgSHcBRJAov1cxRnIjdPjSiGUqjW1nPSZgJzHMcCmErSNAW82+t9+/S58ZUte63CoKisVMNGa0tBGf2fO66fWSjKfIjZygWXHdmzee9uLFrIOWmDsMofEDXLEQHvBcMw92Csyo622hWMoYI5PhZN2MIYbXCguIiK1TR5HeiyfV94VZNS7kDNbFdY/Z0TXVdoK+LQxYj3tMlsIe71rBMDsgPmd1Zyp0GaqnR1gnz9CnipbSjYUKNxyvIEZyNHOb/jxzWu5LD87wqgOs48w3fbj6/SxXPORtVukv1qPI2cQ+s43HfPTFDnIfUEIe6OOdz9dRDXTtwO7Fq2q4feEOx2hzevQLgaPUxXEkUhUf75G9qgpAmkqA1y+YwwUT6/gtiEUyhEqsvQ4B1qruDr0eq5Vcwt9li+85AZVCVCyevDGxwPAhkEZft9YD65gcuq+Hmiz3jAZ0AU98Z8AzwBxIJqDLJ6WumnmO+fLz9C9RX8iUbLvH3lfMbZbUs6FPKEkiGS3rg+obA2xD7msuCcE8R38Fos8IcPWawyNUbwVWdlSPZoLMPjOOHM1CLT+Vfj+gpTVE1WZkO9hJ4FOUOxPTBM+nMsTR0Rx+VaQU4WZFrf8A0+pEhhrMVYpDkRtYpMS4j754cM6XGcbUEMXCj8vw+oN5b4TniOnXF8xCeUx3P6TvjaY8ohd78FARmtb9LOgb7l6PiGDTPcwz612Pw9yl4/Gp25liqflS85s0Xg3aZ5yAYcXu4AnoRB6FoNj9ml18hNP8xYD/8Bw== \ No newline at end of file diff --git a/docs/draw.io/vpn_s2s_ikev2.drawio b/docs/draw.io/vpn_s2s_ikev2.drawio deleted file mode 100644 index b240c191..00000000 --- a/docs/draw.io/vpn_s2s_ikev2.drawio +++ /dev/null @@ -1 +0,0 @@ -7Zrdk6I4EMD/Gh+lSMLn4zgz7j7cVk3V1H3svWxFiJhaIB7EUfevv4QEIYCje6eOW4XzIOmQTtL5ddP0OEGP2e5TgderLywm6QTa8W6CniYQIoCA+JKSvZJA2/WVJClorGSgEbzSH0QLbS3d0JiUxo2csZTTtSmMWJ6TiBsyXBRsa962ZKk56xonpCd4jXDal/5JY77SUmDbTcdnQpOVnjpwdccCR9+Tgm1yPd8EomX1Ud0ZrnXp+8sVjtm2JULPE/RYMMbVVbZ7JKk0bm02NW5+pPew7oLk/JwBv/tf4d9PP749rV+/8DAihK2iqRwg1bzhdEPqfVSr5fvaQtUeidQCJmi2XVFOXtc4kr1bAYWQrXiW6m6tjhSc7I4uFBy2L7giLCO82Itb9ICp43pqjGZqilytZNuckOM4SrZqHQ6qccSaiuSgvbGMuNDG+RlDgTs0FLADdHeWOsNQwhXW8jLbJTKqWBEtI2YJ83FSlPrbtFaMy1VlWVs0ljRNH1nKikobspEXhL6Ql7xg30mrR/tj3VP7tzDpTBqeiijwG16Q9IWVlFOWi74F45xlrRseUprIDs7kATZHLBdycGnZiFhGo3qFLOdznNFUnssfpIhxjrVYR0AAL8aA65gMwNDtMYCCAQZAEF7LW0YGbsmAg+4PATQicEsEfMe3XBOCAKCPhsA5DQGJRTqmmyVJMrHh50Y0I3n8ILM80ZuznJg4kB3lf0lbi62r1ldteXn9tGs39q0zabExQ/O55/Vpil0SxM4QTZ43g/N5jyakJ3ohBRXGk+SqyXNhSLXI6rCrdrVMK6ybzUqr1r7d6uuL51SeQtVS5pQ2fB8cYXK2KSJy+rnNcZEQfsqx+yC2IKsz5DZjtawgKeb0zVzuEHd6hhdGxUYazgMPWQFqPp30B3qmRrVrraSdHPf0hu/p9UPf8lof15xF2aw3iwAX71u3reUN5bubOxLHjy+7O8LxT4zwbfDuCHGh1t14/eGU/3sgcMdA0AoEQXDPgQD+EoHA8aDhsHbHZcWbutVx07ODAfKBBfruXqt2PTAQKy4dDKADf9K1nbqmclPXBkOZnpeK454txEXCKzqVQPqc4fXePxtWd0zLKid6EDeAYL1rOmstwIcWCCzRbYmNzqFTqxUNpdmcTYhbK+iEG5FrcTOImA6ug0w7GmgR1qlgJDyrSlC7OWJG47iKWUMlADN1vETq13sGuHY/+weO2/fFujR1+RrAUOJ3FSYs6I4YqAd7FwOvrvu0a0H+LSkYeupfhwIZ+UYI4DSEdvc1EDWiDwPBG8PBrUlw7LsLB/4YDm4MAewWBg9l/w+DILh5tgjHbLH9bhPeXbYYHkXi/xHwxmkTCBZF98DLNc6PK9/qnUv1OSsynA4gZlvyT25f+tWBI6W5h5dJXYewE/8uPLPibJYiwOSsGrQz6VU9lq78O4q5HKyXDgaQVkXyS9AK7O7LdwgGshlYv/0blQZ0JV5rR/hlgUUjsNcCtle1Ce2PpvUK7+LQGcK3qHYzPmWrUlwv8Rp8CxsokF7tMQuv8Do+DEJKliMH+vnldP9FNZSBXwYD0Wx+TqbKu82P9tDzvw== \ No newline at end of file diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index 9a13e2b3..00000000 --- a/docs/history.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _history: - -####### -History -####### - -VyOS is a Linux-based network operating system that provides software-based -network routing, firewall, and VPN functionality. - -The VyOS project was started in late 2013 as a community fork of the -`GPL `_ portions of -Vyatta Core 6.6R1 with the goal of maintaining a free and open source network -operating system in response to the decision to discontinue the community -edition of Vyatta. Here everyone loves learning, older managers and new users. - -VyOS is primarily based on `Debian GNU/Linux `_ and -the `Quagga `_ routing engine. Its configuration -syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the -`XORP project `_, which was the original routing engine -for Vyatta. - -In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of -VyOS version 1.2, VyOS now uses `FRRouting `_ as the -routing engine. - -How is VyOS different from any other router distributions and platform? - -- It's more than just a firewall and VPN, VyOS includes extended routing - capabilities like OSPFv2, OSPFv3, BGP, VRRP, and extensive route policy - mapping and filtering -- Unified command line interface in the style of hardware routers. -- Scriptable CLI -- Stateful configuration system: prepare changes and commit at once or discard, - view previous revisions or rollback to them, archive revisions to remote - server and execute hooks at commit time -- Image-based upgrade: keep multiple versions on the same system and revert to - previous image if a problem arises -- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard, DPMVPN, IKEv2 and more -- DHCP, TFTP, mDNS repeater, broadcast relay and DNS forwarding support -- Both IPv4 and IPv6 support -- Runs on physical and virtual platforms alike: small x86 boards, big servers, - KVM, Xen, VMware, Hyper-V, and more -- Completely free and open source, with documented internal APIs and build - procedures -- Community driven. Patches are welcome and all code, bugs, and nightly builds - are publicly accessible - diff --git a/docs/index.rst b/docs/index.rst index ab9d3f66..3322bf8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,102 +6,44 @@ VyOS User Guide .. toctree:: - :caption: Introduction - :name: intro :maxdepth: 2 + :hidden: + :caption: FIND CAPTION NAME - about - history - install - cli - quick-start - + introducing/about + introducing/history + introducing/releases + changelog/index .. toctree:: - :caption: Basic Configuration - :name: basics :maxdepth: 2 + :hidden: + :includehidden: + :caption: first steps - configuration-overview - interfaces/basic-index - system/basic-index - image-mgmt - - -.. toctree:: - :caption: Advanced Configuration - :name: advanced - :maxdepth: 2 - - interfaces/advanced-index - system/advanced-index - services/index - firewall - routing/index - vrf - nat - nptv6 - qos - high-availability - vpn/index - load-balancing - command-list-configuration - + installation/index + quick-start + cli + .. toctree:: - :caption: System Operation - :name: system-operation :maxdepth: 2 + :hidden: + :includehidden: + :caption: Adminguide - information - troubleshooting - command-list-operation + configuration/index + operation/index + automation/index + troubleshooting/index + configexamples/index .. toctree:: - :caption: Appendix - :name: appendix :maxdepth: 2 - - appendix/release-notes - appendix/examples/index - appendix/vyos-on-baremetal - appendix/virtual/index - appendix/vyos-on-clouds - appendix/migrate-from-vyatta - appendix/command-scripting - appendix/http-api - - -.. toctree:: + :hidden: + :includehidden: :caption: Contributing - :name: contributing - :maxdepth: 2 - - contributing/build-vyos - contributing/upstream-packages - contributing/issues-features - contributing/development - contributing/debugging - contributing/documentation - - -################ -Copyright Notice -################ - -Copyright (C) 2018-2020 VyOS maintainers and contributors - -Permission is granted to make and distribute verbatim copies of this manual -provided the copyright notice and this permission notice are preserved on all -copies. - -Permission is granted to copy and distribute modified versions of this manual -under the conditions for verbatim copying, provided that the entire resulting -derived work is distributed under the terms of a permission notice identical -to this one. -Permission is granted to copy and distribute translations of this manual into -another language, under the above conditions for modified versions, except that -this permission notice may be stated in a translation approved by the VyOS -maintainers. + contributing/index + copyright diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 11d0fc88..00000000 --- a/docs/install.rst +++ /dev/null @@ -1,514 +0,0 @@ -.. _installation: - -############ -Installation -############ - -VyOS installation requires to download a VyOS .iso file. That file is -a live install image that lets you boot a live VyOS. From that live -system you can proceed to the permanent installation on a hard drive or -any other type of storage. - - -Hardware requirements -===================== - -The minimum system requirements are 512 MiB RAM and 2 GiB storage. -Depending on your use you might need additional RAM and CPU resources e.g. -when having multiple BGP full tables in your system. - -Download -======== - -Registered Subscribers ----------------------- - -Registered subscribers can log into https://support.vyos.io/ to have access to -a variety of different downloads via the "Downloads" link. These downloads -include LTS (Long-Term-Support) and associated hot-fix releases, early public -access releases, pre-built VM images, as well as device specific installation -ISOs. - -.. figure:: /_static/images/vyos-downloads.png - -Building from source ----------------------- - -Non-subscribers can always get the LTS release by building it from source. -Instruction can be found in the :ref:`build` section of this manual. VyOS -source code repository is available for everyone at -https://github.com/vyos/vyos-build. - -Rolling Release ---------------- - -Everyone can download bleeding-edge VyOS rolling images from: -https://downloads.vyos.io/ - -.. note:: Rolling releases contain all the latest enhancements and fixes. This - means that there will be new bugs of course. If you think you hit a bug - please follow the guide at :ref:`bug_report`. To improve VyOS we depend on - your feedback! - -The following link will always fetch the most recent VyOS build for AMD64 -systems from the current branch: -https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - - -Download Verification ---------------------- - -LTS images are signed by VyOS lead package-maintainer private key. With -the official public key, the authenticity of the package can be -verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. - -.. note:: This subsection only applies e applies to LTS images, for - Rolling images please jump to :ref:`live_installation`. - -Preparing for the verification -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First, install GPG or another OpenPGP implementation. On most GNU+Linux -distributions it is installed by default as package managers use it to -verify package signatures. If not pre-installed, it will need to be -downloaded and installed. - -The official VyOS public key can be retrieved in a number of ways. Skip -to :ref:`gpg-verification` if the key is already present. - -It can be retrieved directly from a key server: - -``gpg --recv-keys FD220285A0FE6D7E`` - -Or it can be accessed via a web browser: - -https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E - -Or from the following block: - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - mQINBFXKsiIBEACyid9PR/v56pSRG8VgQyRwvzoI7rLErZ8BCQA2WFxA6+zNy+6G - +0E/6XAOzE+VHli+wtJpiVJwAh+wWuqzOmv9css2fdJxpMW87pJAS2i3EVVVf6ab - wU848JYLGzc9y7gZrnT1m2fNh4MXkZBNDp780WpOZx8roZq5X+j+Y5hk5KcLiBn/ - lh9Zoh8yzrWDSXQsz0BGoAbVnLUEWyo0tcRcHuC0eLx6oNG/IHvd/+kxWB1uULHU - SlB/6vcx56lLqgzywkmhP01050ZDyTqrFRIfrvw6gLQaWlgR3lB93txvF/sz87Il - VblV7e6HEyVUQxedDS8ikOyzdb5r9a6Zt/j8ZPSntFNM6OcKAI7U1nDD3FVOhlVn - 7lhUiNc+/qjC+pR9CrZjr/BTWE7Zpi6/kzeH4eAkfjyALj18oC5udJDjXE5daTL3 - k9difHf74VkZm29Cy9M3zPckOZpsGiBl8YQsf+RXSBMDVYRKZ1BNNLDofm4ZGijK - mriXcaY+VIeVB26J8m8y0zN4/ZdioJXRcy72c1KusRt8e/TsqtC9UFK05YpzRm5R - /nwxDFYb7EdY/vHUFOmfwXLaRvyZtRJ9LwvRUAqgRbbRZg3ET/tn6JZk8hqx3e1M - IxuskOB19t5vWyAo/TLGIFw44SErrq9jnpqgclTSRgFjcjHEm061r4vjoQARAQAB - tDZWeU9TIE1haW50YWluZXJzIChWeU9TIFJlbGVhc2UpIDxtYWludGFpbmVyc0B2 - eW9zLm5ldD6JAjgEEwECACIFAlXKsiICGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4B - AheAAAoJEP0iAoWg/m1+xbgP+QEDYZi5dA4IPY+vU1L95Bavju2m2o35TSUDPg5B - jfAGuhbsNUceU+l/yUlxjpKEmvshyW3GHR5QzUaKGup/ZDBo1CBxZNhpSlFida2E - KAYTx4vHk3MRXcntiAj/hIJwRtzCUp5UQIqHoU8dmHoHOkKEP+zhJuR6E2s+WwDr - nTwE6eRa0g/AHY+chj2Je6flpPm2CKoTfUE7a2yBBU3wPq3rGtsQgVxPAxHRZz7A - w4AjH3NM1Uo3etuiDnGkJAuoKKb1J4X3w2QlbwlR4cODLKhJXHIufwaGtRwEin9S - 1l2bL8V3gy2Hv3D2t9TQZuR5NUHsibJRXLSa8WnSCcc6Bij5aqfdpYB+YvKH/rIm - GvYPmLZDfKGkx0JE4/qtfFjiPJ5VE7BxNyliEw/rnQsxWAGPqLlL61SD8w5jGkw3 - CinwO3sccTVcPz9b6A1RsbBVhTJJX5lcPn1lkOEVwQ7l8bRhOKCMe0P53qEDcLCd - KcXNnAFbVes9u+kfUQ4oxS0G2JS9ISVNmune+uv+JR7KqSdOuRYlyXA9uTjgWz4y - Cs7RS+CpkJFqrqOtS1rmuDW9Ea4PA8ygGlisM5d/AlVkniHz/2JYtgetiLCj9mfE - MzQpgnldNSPumKqJ3wwmCNisE+lXQ5UXCaoaeqF/qX1ykybQn41LQ+0xT5Uvy7sL - 9IwGuQINBFXKsiIBEACg2mP3QYkXdgWTK5JyTGyttE6bDC9uqsK8dc1J66Tjd5Ly - Be0amO+88GHXa0o5Smwk2QNoxsRR41G/D/eAeGsuOEYnePROEr3tcLnDjo4KLgQ+ - H69zRPn77sdP3A34Jgp+QIzByJWM7Cnim31quQP3qal2QdpGJcT/jDJWdticN76a - Biaz+HN13LyvZM+DWhUDttbjAJc+TEwF9YzIrU+3AzkTRDWkRh4kNIQxjlpNzvho - 9V75riVqg2vtgPwttPEhOLb0oMzy4ADdfezrfVvvMb4M4kY9npu4MlSkNTM97F/I - QKy90JuSUIjE05AO+PDXJF4Fd5dcpmukLV/2nV0WM2LAERpJUuAgkZN6pNUFVISR - +nSfgR7wvqeDY9NigHrJqJbSEgaBUs6RTk5hait2wnNKLJajlu3aQ2/QfRT/kG3h - ClKUz3Ju7NCURmFE6mfsdsVrlIsEjHr/dPbXRswXgC9FLlXpWgAEDYi9Wdxxz8o9 - JDWrVYdKRGG+OpLFh8AP6QL3YnZF+p1oxGUQ5ugXauAJ9YS55pbzaUFP8oOO2P1Q - BeYnKRs1GcMI8KWtE/fze9C9gZ7Dqju7ZFEyllM4v3lzjhT8muMSAhw41J22mSx6 - VRkQVRIAvPDFES45IbB6EEGhDDg4pD2az8Q7i7Uc6/olEmpVONSOZEEPsQe/2wAR - AQABiQIfBBgBAgAJBQJVyrIiAhsMAAoJEP0iAoWg/m1+niUQAKTxwJ9PTAfB+XDk - 3qH3n+T49O2wP3fhBI0EGhJp9Xbx29G7qfEeqcQm69/qSq2/0HQOc+w/g8yy71jA - 6rPuozCraoN7Im09rQ2NqIhPK/1w5ZvgNVC0NtcMigX9MiSARePKygAHOPHtrhyO - rJQyu8E3cV3VRT4qhqIqXs8Ydc9vL3ZrJbhcHQuSLdZxM1k+DahCJgwWabDCUizm - sVP3epAP19FP8sNtHi0P1LC0kq6/0qJot+4iBiRwXMervCD5ExdOm2ugvSgghdYN - BikFHvmsCxbZAQjykQ6TMn+vkmcEz4fGAn4L7Nx4paKEtXaAFO8TJmFjOlGUthEm - CtHDKjCTh9WV4pwG2WnXuACjnJcs6LcK377EjWU25H4y1ff+NDIUg/DWfSS85iIc - UgkOlQO6HJy0O96L5uxn7VJpXNYFa20lpfTVZv7uu3BC3RW/FyOYsGtSiUKYq6cb - CMxGTfFxGeynwIlPRlH68BqH6ctR/mVdo+5UIWsChSnNd1GreIEI6p2nBk3mc7jZ - 7pTEHpjarwOjs/S/lK+vLW53CSFimmW4lw3MwqiyAkxl0tHAT7QMHH9Rgw2HF/g6 - XD76fpFdMT856dsuf+j2uuJFlFe5B1fERBzeU18MxML0VpDmGFEaxxypfACeI/iu - 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb - =Ld8S - -----END PGP PUBLIC KEY BLOCK----- - -Store the key in a new text file and import it into GPG via: ``gpg --import -file_with_the_public_key`` - -The import can be verified with: - -.. code-block:: none - - $ gpg --list-keys - ... - pub rsa4096 2015-08-12 [SC] - 0694A9230F5139BF834BA458FD220285A0FE6D7E - uid [ unknown] VyOS Maintainers (VyOS Release) - sub rsa4096 2015-08-12 [E] - -.. _gpg-verification: - -GPG verification -^^^^^^^^^^^^^^^^ - -With the public key imported, the signature for the desired image needs -to be downloaded. - -.. note:: The signature can be downloaded by appending `.asc` to the URL of the - downloaded VyOS image. That small *.asc* file is the signature for the - associated image. - -Finally, verify the authenticity of the downloaded image: - -.. code-block:: none - - $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso - gpg: Signature made So 14 Apr 12:58:07 2019 CEST - gpg: using RSA key FD220285A0FE6D7E - gpg: Good signature from "VyOS Maintainers (VyOS Release) " [unknown] - Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E - -.. _live_installation: - -Live installation -================= - -.. note:: A permanent VyOS installation always requires to go first - through a live installation. - -VyOS, as other GNU+Linux distributions, can be tasted without installing -it in your hard drive. **With your downloaded VyOS .iso file you can -create a bootable USB drive that will let you boot into a fully -functional VyOS system**. Once you have tested it, you can either decide -to begin a :ref:`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everythng as it was. - - -If you have a GNU+Linux system, you can create your VyOS bootable USB -stick with with the ``dd`` command: - - 1. Open your terminal emulator. - - 2. Find out the device name of your USB drive (you can use the ``lsblk`` - command) - - 3. Unmount the USB drive. Replace X in the example below with the - letter of your device and keep the asterisk (wildcard) to unmount - all partitions. - - .. code-block:: none - - $ umount /dev/sdX* - - 4. Write the image (your VyOS .iso file) to the USB drive. - Note that here you want to use the device name (e.g. /dev/sdb), not - the partition name (e.g. /dev/sdb1). - - **Warning**: This will destroy all data on the USB drive! - - .. code-block:: none - - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync - - 5. Wait until you get the outcome (bytes copied). Be patient, in some - computers it might take more than one minute. - - 6. Once ``dd`` has finished, pull the USB drive out and plug it into - the powered-off computer where you want to install (or test) VyOS. - - 7. Power the computer on, making sure it boots from the USB drive (you - might need to select booting device or change booting settings). - - 8. Once VyOS is completely loaded, enter the default credentials - (login: vyos, password: vyos). - - -If you find difficulties with this method, prefer to use a GUI program, -or have a different operating system, there are other programs you can -use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, -macOS and Windows), Rufus_ (for Windows) and `many others`_. You can -follow their instructions to create a bootable USB drive from an .iso -file. - -.. hint:: The default username and password for the live system is *vyos*. - - -.. _permanent_installation: - -Permanent installation -====================== - -.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`. - -Unlike general purpose Linux distributions, VyOS uses "image installation" that -mimics the user experience of traditional hardware routers and allows keeping -multiple VyOS versions installed simultaneously. This makes it possible to -switch to a previous version if something breaks or miss-behaves after an image -upgrade. - -Every version is contained in its own squashfs image that is mounted in a union -filesystem together with a directory for mutable data such as configurations, -keys, or custom scripts. - -.. note:: Older versions (prior to VyOS 1.1) used to support non-image - installation (``install system`` command). Support for this has been removed - from VyOS 1.2 and newer releases. Older releases can still be upgraded via - the general ``add system image `` upgrade command (consult - :ref:`image-mgmt` for further information). - - -In order to proceed with a permanent installation: - - 1. Log into the VyOS live system (use the default credentials: vyos, - vyos) - - 2. Run the ``install image`` command and follow the wizard: - - .. code-block:: none - - vyos@vyos:~$ install image - Welcome to the VyOS install program. This script - will walk you through the process of installing the - VyOS image to a local hard drive. - Would you like to continue? (Yes/No) [Yes]: Yes - Probing drives: OK - Looking for pre-existing RAID groups...none found. - The VyOS image will require a minimum 2000MB root. - Would you like me to try to partition a drive automatically - or would you rather partition it manually with parted? If - you have already setup your partitions, you may skip this step - - Partition (Auto/Parted/Skip) [Auto]: - - I found the following drives on your system: - sda 4294MB - - Install the image on? [sda]: - - This will destroy all data on /dev/sda. - Continue? (Yes/No) [No]: Yes - - How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: - - Creating filesystem on /dev/sda1: OK - Done! - Mounting /dev/sda1... - What would you like to name this image? [1.2.0-rolling+201809210337]: - OK. This image will be named: 1.2.0-rolling+201809210337 - Copying squashfs image... - Copying kernel and initrd images... - Done! - I found the following configuration files: - /opt/vyatta/etc/config.boot.default - Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: - - Copying /opt/vyatta/etc/config.boot.default to sda. - Enter password for administrator account - Enter password for user 'vyos': - Retype password for user 'vyos': - I need to install the GRUB boot loader. - I found the following drives on your system: - sda 4294MB - - Which drive should GRUB modify the boot partition on? [sda]: - - Setting up grub: OK - Done! - - - 3. After the installation is complete, remove the live USB stick or - CD. - - 4. Reboot the system. - - .. code-block:: none - - vyos@vyos:~$ reboot - Proceed with reboot? (Yes/No) [No] Yes - - You will boot now into a permanent VyOS system. - - -PXE Boot -======== - -VyOS can also be installed through PXE. This is a more complex -installation method which allows deploying VyOS through the network. - -**Requirements** - -* Clients (where VyOS is to be installed) with a PXE-enabled NIC -* :ref:`dhcp-server` -* :ref:`tftp-server` -* Webserver (HTTP) - optional, but we will use it to speed up installation -* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution `_ - -Configuration -------------- - -Step 1: DHCP -^^^^^^^^^^^^ - -Configure a DHCP server to provide the client with: - -* An IP address -* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -.. code-block:: none - - vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - } - } - -.. _install_from_tftp: - -Step 2: TFTP -^^^^^^^^^^^^ - -Configure a TFTP server so that it serves the following: - -* The *pxelinux.0* file from the Syslinux distribution -* The *ldlinux.c32* file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the - *vmlinuz* file inside the */live* directory of the extracted - contents from the ISO file. -* The initial ramdisk of the VyOS ISO you want to deploy. That is the - *initrd.img* file inside the */live* directory of the extracted - contents from the ISO file. Do not use an empty (0 bytes) initrd.img - file you might find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration - file. We will use the configuration_ file shown below, which we named - default_. - -.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config -.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration - -In the example we configured our existent VyOS as the TFTP server too: - -.. code-block:: none - - vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 - -Example of the contents of the TFTP server: - -.. code-block:: none - - vyos@vyos# ls -hal /config/tftpboot/ - total 29M - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . - drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. - -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos - -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 - -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg - -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - - vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg - total 12K - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. - -rw-r--r-- 1 root root 191 Oct 14 01:10 default - -Example of simple (no menu) configuration file: - -.. code-block:: none - - vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default - DEFAULT VyOS123 - - LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs - -Step 3: HTTP -^^^^^^^^^^^^ - -We also need to provide the *filesystem.squashfs* file. That is a heavy -file and TFTP is slow, so you could send it through HTTP to speed up the -transfer. That is how it is done in our example, you can find that in -the configuration file above. - -**First** run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` -file. The file can be found inside the `/live` directory of the -extracted contents of the ISO file. - -**Second**, edit the configuration file of the :ref:`install_from_tftp` -so that it shows the correct URL at -``fetch=http:///filesystem.squashfs``. - -.. note:: Do not change the name of the *filesystem.squashfs* file. If - you are working with different versions, you can create different - directories instead. - -And **third**, restart the TFTP service. If you are using VyOS as your -TFTP Server, you can restart the service with -``sudo service tftpd-hpa restart``. - -.. note:: Make sure the available directories and files in both TFTP - and HTTP server have the right permissions to be accessed from the - booting clients. - -.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html - -Client Boot ------------ - -Finally, turn on your PXE-enabled client or clients. They will -automatically get an IP address from the DHCP server and start booting -into VyOS live from the files automatically taken from the TFTP and HTTP -servers. - -Once finished you will be able to proceed with the ``install image`` -command as in a regular VyOS installation. - - - -Known Issues -============ - -This is a list of known issues that can arise during installation. - -Black screen on install ------------------------ - -GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. -This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a -black screen after selecting the `Live system` option from the installation image. - -The workaround is to type `e` when the boot menu appears and edit the GRUB boot options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - -.. _SYSLINUX: http://www.syslinux.org/ -.. _balenaEtcher: https://www.balena.io/etcher/ -.. _Rufus: https://rufus.ie/ -.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems diff --git a/docs/installation/index.rst b/docs/installation/index.rst new file mode 100644 index 00000000..af265121 --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,18 @@ +################################# +Installation and Image Management +################################# + + + +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + iso + virtual/index + cloud/index + update + image + migrate-from-vyatta + ../vyos-on-baremetal \ No newline at end of file diff --git a/docs/installation/install.rst b/docs/installation/install.rst new file mode 100644 index 00000000..11d0fc88 --- /dev/null +++ b/docs/installation/install.rst @@ -0,0 +1,514 @@ +.. _installation: + +############ +Installation +############ + +VyOS installation requires to download a VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From that live +system you can proceed to the permanent installation on a hard drive or +any other type of storage. + + +Hardware requirements +===================== + +The minimum system requirements are 512 MiB RAM and 2 GiB storage. +Depending on your use you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. + +Download +======== + +Registered Subscribers +---------------------- + +Registered subscribers can log into https://support.vyos.io/ to have access to +a variety of different downloads via the "Downloads" link. These downloads +include LTS (Long-Term-Support) and associated hot-fix releases, early public +access releases, pre-built VM images, as well as device specific installation +ISOs. + +.. figure:: /_static/images/vyos-downloads.png + +Building from source +---------------------- + +Non-subscribers can always get the LTS release by building it from source. +Instruction can be found in the :ref:`build` section of this manual. VyOS +source code repository is available for everyone at +https://github.com/vyos/vyos-build. + +Rolling Release +--------------- + +Everyone can download bleeding-edge VyOS rolling images from: +https://downloads.vyos.io/ + +.. note:: Rolling releases contain all the latest enhancements and fixes. This + means that there will be new bugs of course. If you think you hit a bug + please follow the guide at :ref:`bug_report`. To improve VyOS we depend on + your feedback! + +The following link will always fetch the most recent VyOS build for AMD64 +systems from the current branch: +https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + + +Download Verification +--------------------- + +LTS images are signed by VyOS lead package-maintainer private key. With +the official public key, the authenticity of the package can be +verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. + +.. note:: This subsection only applies e applies to LTS images, for + Rolling images please jump to :ref:`live_installation`. + +Preparing for the verification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, install GPG or another OpenPGP implementation. On most GNU+Linux +distributions it is installed by default as package managers use it to +verify package signatures. If not pre-installed, it will need to be +downloaded and installed. + +The official VyOS public key can be retrieved in a number of ways. Skip +to :ref:`gpg-verification` if the key is already present. + +It can be retrieved directly from a key server: + +``gpg --recv-keys FD220285A0FE6D7E`` + +Or it can be accessed via a web browser: + +https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E + +Or from the following block: + +.. code-block:: none + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (GNU/Linux) + + mQINBFXKsiIBEACyid9PR/v56pSRG8VgQyRwvzoI7rLErZ8BCQA2WFxA6+zNy+6G + +0E/6XAOzE+VHli+wtJpiVJwAh+wWuqzOmv9css2fdJxpMW87pJAS2i3EVVVf6ab + wU848JYLGzc9y7gZrnT1m2fNh4MXkZBNDp780WpOZx8roZq5X+j+Y5hk5KcLiBn/ + lh9Zoh8yzrWDSXQsz0BGoAbVnLUEWyo0tcRcHuC0eLx6oNG/IHvd/+kxWB1uULHU + SlB/6vcx56lLqgzywkmhP01050ZDyTqrFRIfrvw6gLQaWlgR3lB93txvF/sz87Il + VblV7e6HEyVUQxedDS8ikOyzdb5r9a6Zt/j8ZPSntFNM6OcKAI7U1nDD3FVOhlVn + 7lhUiNc+/qjC+pR9CrZjr/BTWE7Zpi6/kzeH4eAkfjyALj18oC5udJDjXE5daTL3 + k9difHf74VkZm29Cy9M3zPckOZpsGiBl8YQsf+RXSBMDVYRKZ1BNNLDofm4ZGijK + mriXcaY+VIeVB26J8m8y0zN4/ZdioJXRcy72c1KusRt8e/TsqtC9UFK05YpzRm5R + /nwxDFYb7EdY/vHUFOmfwXLaRvyZtRJ9LwvRUAqgRbbRZg3ET/tn6JZk8hqx3e1M + IxuskOB19t5vWyAo/TLGIFw44SErrq9jnpqgclTSRgFjcjHEm061r4vjoQARAQAB + tDZWeU9TIE1haW50YWluZXJzIChWeU9TIFJlbGVhc2UpIDxtYWludGFpbmVyc0B2 + eW9zLm5ldD6JAjgEEwECACIFAlXKsiICGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4B + AheAAAoJEP0iAoWg/m1+xbgP+QEDYZi5dA4IPY+vU1L95Bavju2m2o35TSUDPg5B + jfAGuhbsNUceU+l/yUlxjpKEmvshyW3GHR5QzUaKGup/ZDBo1CBxZNhpSlFida2E + KAYTx4vHk3MRXcntiAj/hIJwRtzCUp5UQIqHoU8dmHoHOkKEP+zhJuR6E2s+WwDr + nTwE6eRa0g/AHY+chj2Je6flpPm2CKoTfUE7a2yBBU3wPq3rGtsQgVxPAxHRZz7A + w4AjH3NM1Uo3etuiDnGkJAuoKKb1J4X3w2QlbwlR4cODLKhJXHIufwaGtRwEin9S + 1l2bL8V3gy2Hv3D2t9TQZuR5NUHsibJRXLSa8WnSCcc6Bij5aqfdpYB+YvKH/rIm + GvYPmLZDfKGkx0JE4/qtfFjiPJ5VE7BxNyliEw/rnQsxWAGPqLlL61SD8w5jGkw3 + CinwO3sccTVcPz9b6A1RsbBVhTJJX5lcPn1lkOEVwQ7l8bRhOKCMe0P53qEDcLCd + KcXNnAFbVes9u+kfUQ4oxS0G2JS9ISVNmune+uv+JR7KqSdOuRYlyXA9uTjgWz4y + Cs7RS+CpkJFqrqOtS1rmuDW9Ea4PA8ygGlisM5d/AlVkniHz/2JYtgetiLCj9mfE + MzQpgnldNSPumKqJ3wwmCNisE+lXQ5UXCaoaeqF/qX1ykybQn41LQ+0xT5Uvy7sL + 9IwGuQINBFXKsiIBEACg2mP3QYkXdgWTK5JyTGyttE6bDC9uqsK8dc1J66Tjd5Ly + Be0amO+88GHXa0o5Smwk2QNoxsRR41G/D/eAeGsuOEYnePROEr3tcLnDjo4KLgQ+ + H69zRPn77sdP3A34Jgp+QIzByJWM7Cnim31quQP3qal2QdpGJcT/jDJWdticN76a + Biaz+HN13LyvZM+DWhUDttbjAJc+TEwF9YzIrU+3AzkTRDWkRh4kNIQxjlpNzvho + 9V75riVqg2vtgPwttPEhOLb0oMzy4ADdfezrfVvvMb4M4kY9npu4MlSkNTM97F/I + QKy90JuSUIjE05AO+PDXJF4Fd5dcpmukLV/2nV0WM2LAERpJUuAgkZN6pNUFVISR + +nSfgR7wvqeDY9NigHrJqJbSEgaBUs6RTk5hait2wnNKLJajlu3aQ2/QfRT/kG3h + ClKUz3Ju7NCURmFE6mfsdsVrlIsEjHr/dPbXRswXgC9FLlXpWgAEDYi9Wdxxz8o9 + JDWrVYdKRGG+OpLFh8AP6QL3YnZF+p1oxGUQ5ugXauAJ9YS55pbzaUFP8oOO2P1Q + BeYnKRs1GcMI8KWtE/fze9C9gZ7Dqju7ZFEyllM4v3lzjhT8muMSAhw41J22mSx6 + VRkQVRIAvPDFES45IbB6EEGhDDg4pD2az8Q7i7Uc6/olEmpVONSOZEEPsQe/2wAR + AQABiQIfBBgBAgAJBQJVyrIiAhsMAAoJEP0iAoWg/m1+niUQAKTxwJ9PTAfB+XDk + 3qH3n+T49O2wP3fhBI0EGhJp9Xbx29G7qfEeqcQm69/qSq2/0HQOc+w/g8yy71jA + 6rPuozCraoN7Im09rQ2NqIhPK/1w5ZvgNVC0NtcMigX9MiSARePKygAHOPHtrhyO + rJQyu8E3cV3VRT4qhqIqXs8Ydc9vL3ZrJbhcHQuSLdZxM1k+DahCJgwWabDCUizm + sVP3epAP19FP8sNtHi0P1LC0kq6/0qJot+4iBiRwXMervCD5ExdOm2ugvSgghdYN + BikFHvmsCxbZAQjykQ6TMn+vkmcEz4fGAn4L7Nx4paKEtXaAFO8TJmFjOlGUthEm + CtHDKjCTh9WV4pwG2WnXuACjnJcs6LcK377EjWU25H4y1ff+NDIUg/DWfSS85iIc + UgkOlQO6HJy0O96L5uxn7VJpXNYFa20lpfTVZv7uu3BC3RW/FyOYsGtSiUKYq6cb + CMxGTfFxGeynwIlPRlH68BqH6ctR/mVdo+5UIWsChSnNd1GreIEI6p2nBk3mc7jZ + 7pTEHpjarwOjs/S/lK+vLW53CSFimmW4lw3MwqiyAkxl0tHAT7QMHH9Rgw2HF/g6 + XD76fpFdMT856dsuf+j2uuJFlFe5B1fERBzeU18MxML0VpDmGFEaxxypfACeI/iu + 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb + =Ld8S + -----END PGP PUBLIC KEY BLOCK----- + +Store the key in a new text file and import it into GPG via: ``gpg --import +file_with_the_public_key`` + +The import can be verified with: + +.. code-block:: none + + $ gpg --list-keys + ... + pub rsa4096 2015-08-12 [SC] + 0694A9230F5139BF834BA458FD220285A0FE6D7E + uid [ unknown] VyOS Maintainers (VyOS Release) + sub rsa4096 2015-08-12 [E] + +.. _gpg-verification: + +GPG verification +^^^^^^^^^^^^^^^^ + +With the public key imported, the signature for the desired image needs +to be downloaded. + +.. note:: The signature can be downloaded by appending `.asc` to the URL of the + downloaded VyOS image. That small *.asc* file is the signature for the + associated image. + +Finally, verify the authenticity of the downloaded image: + +.. code-block:: none + + $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso + gpg: Signature made So 14 Apr 12:58:07 2019 CEST + gpg: using RSA key FD220285A0FE6D7E + gpg: Good signature from "VyOS Maintainers (VyOS Release) " [unknown] + Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E + +.. _live_installation: + +Live installation +================= + +.. note:: A permanent VyOS installation always requires to go first + through a live installation. + +VyOS, as other GNU+Linux distributions, can be tasted without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a :ref:`permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everythng as it was. + + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the ``dd`` command: + + 1. Open your terminal emulator. + + 2. Find out the device name of your USB drive (you can use the ``lsblk`` + command) + + 3. Unmount the USB drive. Replace X in the example below with the + letter of your device and keep the asterisk (wildcard) to unmount + all partitions. + + .. code-block:: none + + $ umount /dev/sdX* + + 4. Write the image (your VyOS .iso file) to the USB drive. + Note that here you want to use the device name (e.g. /dev/sdb), not + the partition name (e.g. /dev/sdb1). + + **Warning**: This will destroy all data on the USB drive! + + .. code-block:: none + + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync + + 5. Wait until you get the outcome (bytes copied). Be patient, in some + computers it might take more than one minute. + + 6. Once ``dd`` has finished, pull the USB drive out and plug it into + the powered-off computer where you want to install (or test) VyOS. + + 7. Power the computer on, making sure it boots from the USB drive (you + might need to select booting device or change booting settings). + + 8. Once VyOS is completely loaded, enter the default credentials + (login: vyos, password: vyos). + + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, +macOS and Windows), Rufus_ (for Windows) and `many others`_. You can +follow their instructions to create a bootable USB drive from an .iso +file. + +.. hint:: The default username and password for the live system is *vyos*. + + +.. _permanent_installation: + +Permanent installation +====================== + +.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`. + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +.. note:: Older versions (prior to VyOS 1.1) used to support non-image + installation (``install system`` command). Support for this has been removed + from VyOS 1.2 and newer releases. Older releases can still be upgraded via + the general ``add system image `` upgrade command (consult + :ref:`image-mgmt` for further information). + + +In order to proceed with a permanent installation: + + 1. Log into the VyOS live system (use the default credentials: vyos, + vyos) + + 2. Run the ``install image`` command and follow the wizard: + + .. code-block:: none + + vyos@vyos:~$ install image + Welcome to the VyOS install program. This script + will walk you through the process of installing the + VyOS image to a local hard drive. + Would you like to continue? (Yes/No) [Yes]: Yes + Probing drives: OK + Looking for pre-existing RAID groups...none found. + The VyOS image will require a minimum 2000MB root. + Would you like me to try to partition a drive automatically + or would you rather partition it manually with parted? If + you have already setup your partitions, you may skip this step + + Partition (Auto/Parted/Skip) [Auto]: + + I found the following drives on your system: + sda 4294MB + + Install the image on? [sda]: + + This will destroy all data on /dev/sda. + Continue? (Yes/No) [No]: Yes + + How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: + + Creating filesystem on /dev/sda1: OK + Done! + Mounting /dev/sda1... + What would you like to name this image? [1.2.0-rolling+201809210337]: + OK. This image will be named: 1.2.0-rolling+201809210337 + Copying squashfs image... + Copying kernel and initrd images... + Done! + I found the following configuration files: + /opt/vyatta/etc/config.boot.default + Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: + + Copying /opt/vyatta/etc/config.boot.default to sda. + Enter password for administrator account + Enter password for user 'vyos': + Retype password for user 'vyos': + I need to install the GRUB boot loader. + I found the following drives on your system: + sda 4294MB + + Which drive should GRUB modify the boot partition on? [sda]: + + Setting up grub: OK + Done! + + + 3. After the installation is complete, remove the live USB stick or + CD. + + 4. Reboot the system. + + .. code-block:: none + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes + + You will boot now into a permanent VyOS system. + + +PXE Boot +======== + +VyOS can also be installed through PXE. This is a more complex +installation method which allows deploying VyOS through the network. + +**Requirements** + +* Clients (where VyOS is to be installed) with a PXE-enabled NIC +* :ref:`dhcp-server` +* :ref:`tftp-server` +* Webserver (HTTP) - optional, but we will use it to speed up installation +* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution `_ + +Configuration +------------- + +Step 1: DHCP +^^^^^^^^^^^^ + +Configure a DHCP server to provide the client with: + +* An IP address +* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +.. code-block:: none + + vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } + +.. _install_from_tftp: + +Step 2: TFTP +^^^^^^^^^^^^ + +Configure a TFTP server so that it serves the following: + +* The *pxelinux.0* file from the Syslinux distribution +* The *ldlinux.c32* file from the Syslinux distribution +* The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +* The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +* A directory named pxelinux.cfg which must contain the configuration + file. We will use the configuration_ file shown below, which we named + default_. + +.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config +.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration + +In the example we configured our existent VyOS as the TFTP server too: + +.. code-block:: none + + vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 + +Example of the contents of the TFTP server: + +.. code-block:: none + + vyos@vyos# ls -hal /config/tftpboot/ + total 29M + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . + drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. + -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos + -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 + -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg + -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + + vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg + total 12K + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. + -rw-r--r-- 1 root root 191 Oct 14 01:10 default + +Example of simple (no menu) configuration file: + +.. code-block:: none + + vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default + DEFAULT VyOS123 + + LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs + +Step 3: HTTP +^^^^^^^^^^^^ + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http:///filesystem.squashfs``. + +.. note:: Do not change the name of the *filesystem.squashfs* file. If + you are working with different versions, you can create different + directories instead. + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +``sudo service tftpd-hpa restart``. + +.. note:: Make sure the available directories and files in both TFTP + and HTTP server have the right permissions to be accessed from the + booting clients. + +.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html + +Client Boot +----------- + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. + + + +Known Issues +============ + +This is a list of known issues that can arise during installation. + +Black screen on install +----------------------- + +GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. +This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a +black screen after selecting the `Live system` option from the installation image. + +The workaround is to type `e` when the boot menu appears and edit the GRUB boot options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + +.. _SYSLINUX: http://www.syslinux.org/ +.. _balenaEtcher: https://www.balena.io/etcher/ +.. _Rufus: https://rufus.ie/ +.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems diff --git a/docs/introducing/about.rst b/docs/introducing/about.rst new file mode 100644 index 00000000..0411344b --- /dev/null +++ b/docs/introducing/about.rst @@ -0,0 +1,27 @@ +.. _about: + +##### +About +##### + +VyOS is an open source network operating system based on Debian GNU/Linux. + +VyOS provides a free routing platform that competes directly with other +commercially available solutions from well known network providers. Because +VyOS is run on standard amd64, i586 and ARM systems, it is able to be used +as a router and firewall platform for cloud deployments. + +We use multiple live versions of our manual hosted thankfully by +https://readthedocs.org. We will provide one version of the manual for every +VyOS major version starting with VyOS 1.2 which will receive Long-term support +(LTS). + +The manual version is selected/specified by it's Git branch name. You can +switch between versions of the documentation by selecting the appropriate +branch on the bottom left corner. + +VyOS CLI syntax may change between major (and sometimes minor) versions. Please +always refer to the documentation matching your current, running installation. +If a change in the CLI is required, VyOS will ship a so called migration script +which will take care of adjusting the syntax. No action needs to be taken by +you. diff --git a/docs/introducing/history.rst b/docs/introducing/history.rst new file mode 100644 index 00000000..9a13e2b3 --- /dev/null +++ b/docs/introducing/history.rst @@ -0,0 +1,47 @@ +.. _history: + +####### +History +####### + +VyOS is a Linux-based network operating system that provides software-based +network routing, firewall, and VPN functionality. + +The VyOS project was started in late 2013 as a community fork of the +`GPL `_ portions of +Vyatta Core 6.6R1 with the goal of maintaining a free and open source network +operating system in response to the decision to discontinue the community +edition of Vyatta. Here everyone loves learning, older managers and new users. + +VyOS is primarily based on `Debian GNU/Linux `_ and +the `Quagga `_ routing engine. Its configuration +syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the +`XORP project `_, which was the original routing engine +for Vyatta. + +In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of +VyOS version 1.2, VyOS now uses `FRRouting `_ as the +routing engine. + +How is VyOS different from any other router distributions and platform? + +- It's more than just a firewall and VPN, VyOS includes extended routing + capabilities like OSPFv2, OSPFv3, BGP, VRRP, and extensive route policy + mapping and filtering +- Unified command line interface in the style of hardware routers. +- Scriptable CLI +- Stateful configuration system: prepare changes and commit at once or discard, + view previous revisions or rollback to them, archive revisions to remote + server and execute hooks at commit time +- Image-based upgrade: keep multiple versions on the same system and revert to + previous image if a problem arises +- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard, DPMVPN, IKEv2 and more +- DHCP, TFTP, mDNS repeater, broadcast relay and DNS forwarding support +- Both IPv4 and IPv6 support +- Runs on physical and virtual platforms alike: small x86 boards, big servers, + KVM, Xen, VMware, Hyper-V, and more +- Completely free and open source, with documented internal APIs and build + procedures +- Community driven. Patches are welcome and all code, bugs, and nightly builds + are publicly accessible + diff --git a/docs/introducing/releases.rst b/docs/introducing/releases.rst new file mode 100644 index 00000000..6d95c4bc --- /dev/null +++ b/docs/introducing/releases.rst @@ -0,0 +1,29 @@ +.. _release: + +######## +Releases +######## + +Rolling Release +############### + +rolling rolling + +LTS +### + +lts lts lts + + +old LTS +======= + +old LTSLTSLTSLTS + +even older LTS +-------------- + +even older LTS even older LTS +even older LTS even older LTS even older LTS even older LTS even older LTS + + diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst deleted file mode 100644 index 0b3420f4..00000000 --- a/docs/troubleshooting.rst +++ /dev/null @@ -1,446 +0,0 @@ -.. _troubleshooting: - -############### -Troubleshooting -############### - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -****************** -Connectivity Tests -****************** - -Basic Connectivity Tests -======================== - -Verifying connectivity can be done with the familiar `ping` and `traceroute` -commands. The options for each are shown (the options for each command were -displayed using the built-in help as described in the :ref:`cli` -section and are omitted from the output here): - -.. opcmd:: ping - - Send ICMP echo requests to destination host. There are multiple options to - ping, inkl. VRF support. - - .. code-block:: none - - vyos@vyos:~$ ping 10.1.1.1 - Possible completions: - Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - vrf - - -.. opcmd:: traceroute - - Trace path to target. - - .. code-block:: none - - vyos@vyos:~$ traceroute - Possible completions: - Track network path to specified node - - - ipv4 Track network path to - ipv6 Track network path to - - -Advanced Connectivity Tests -=========================== - -.. opcmd:: monitor traceroute - - However, another helper is available which combines ping and traceroute - into a single tool. An example of its output is shown: - - .. code-block:: none - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - Keys: Help Display mode Restart statistics Order of fields quit - Packets Pings - Host Loss% Snt Last Avg Best Wrst StDev - 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 - 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 - 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 - 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 - - .. note:: The output consumes the screen and will replace your command - prompt. - - Several options are available for changing the display output. Press `h` to - invoke the built in help system. To quit, just press `q` and you'll be - returned to the VyOS command prompt. - -IPv6 Topology Discovery -======================= - -IPv6 uses different techniques to discover its Neighbors/topology. - -Router Discovery ----------------- - -.. opcmd:: force ipv6-rd interface [address ] - - Discover routers via eth0. - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-rd interface eth0 - Soliciting ff02::2 (ff02::2) on eth0... - - Hop limit : 60 ( 0x3c) - Stateful address conf. : No - Stateful other conf. : No - Mobile home agent : No - Router preference : high - Neighbor discovery proxy : No - Router lifetime : 1800 (0x00000708) seconds - Reachable time : unspecified (0x00000000) - Retransmit time : unspecified (0x00000000) - Prefix : 240e:fe:8ca7:ea01::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Prefix : fc00:470:f1cd:101::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Recursive DNS server : fc00:470:f1cd::ff00 - DNS server lifetime : 600 (0x00000258) seconds - Source link-layer address: 00:98:2B:F8:3F:11 - from fe80::298:2bff:fef8:3f11 - -Neighbor Discovery ------------------- - -.. opcmd:: force ipv6-nd interface address - - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 - - Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... - Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 - - -*************** -Interface names -*************** - -If you find the names of your interfaces have changed, this could be because your MAC addresses have changed. - -* For example, you have a VyOS VM with 4 Ethernet interfaces named eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different host and find your interfaces now are eth4, eth5, eth6 and eth7. - - One way to fix this issue **taking control of the MAC addresses** is: - - Log into VyOS and run this command to display your interface settings. - - .. code-block:: none - - show interfaces detail - - Take note of MAC addresses. - - Now, in order to update a MAC address in the configuration, run this command specifying the interface name and MAC address you want. - - .. code-block:: none - - set interfaces eth0 hw-id 00:0c:29:da:a4:fe - - If it is a VM, go into the settings of the host and set the MAC address to the settings found in the config.boot file. You can also set the MAC to static if the host allows so. - - -* Another example could be when cloning VyOS VMs in GNS3 and you get into the same issue: interface names have changed. - - And **a more generic way to fix it** is just deleting every MAC address at the configuration file of the cloned machine. They will be correctly regenerated automatically. - - -********** -Monitoring -********** - -VyOS features several monitoring tools. - -.. code-block:: none - - vyos@vyos:~$ monitor - Possible completions: - bandwidth Monitor interface bandwidth in real time - bandwidth-test - Initiate or wait for bandwidth test - cluster Monitor clustering service - command Monitor an operational mode command (refreshes every 2 seconds) - conntrack-sync - Monitor conntrack-sync - content-inspection - Monitor Content-Inspection - dhcp Monitor Dynamic Host Control Protocol (DHCP) - dns Monitor a Domain Name Service (DNS) daemon - firewall Monitor Firewall - https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service - lldp Monitor Link Layer Discovery Protocol (LLDP) daemon - log Monitor last lines of messages file - nat Monitor network address translation (NAT) - ndp Monitor the NDP information received by the router through the device - openvpn Monitor OpenVPN - protocol Monitor routing protocols - snmp Monitor Simple Network Management Protocol (SNMP) daemon - stop-all Stop all current background monitoring processes - traceroute Monitor the path to a destination in realtime - traffic Monitor traffic dumps - vpn Monitor VPN - vrrp Monitor Virtual Router Redundancy Protocol (VRRP) - webproxy Monitor Webproxy service - - -Traffic Dumps -============= - -To monitor interface traffic, issue the :code:`monitor traffic interface ` -command, replacing `` with your chosen interface. - -.. code-block:: none - - vyos@vyos:~$ monitor traffic interface eth0 - tcpdump: verbose output suppressed, use -v or -vv for full protocol decode - listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes - 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 - 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 - 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 - 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 - ^C - 4 packets captured - 4 packets received by filter - 0 packets dropped by kernel - vyos@vyos:~$ - -To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command -prompt. - -Traffic can be filtered and saved. - -.. code-block:: none - - vyos@vyos:~$ monitor traffic interface eth0 - Possible completions: - Execute the current command - filter Monitor traffic matching filter conditions - save Save traffic dump from an interface to a file - - -Interface Bandwidth Usage -========================= - -to take a quick view on the used bandwidth of an interface use the ``monitor -bandwidth`` command - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth interface eth0 - -show the following: - -.. code-block:: none - - B (RX Bytes/second) - 198.00 .|....|..................................................... - 165.00 .|....|..................................................... - 132.00 ||..|.|..................................................... - 99.00 ||..|.|..................................................... - 66.00 |||||||..................................................... - 33.00 |||||||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - - KiB (TX Bytes/second) - 3.67 ......|..................................................... - 3.06 ......|..................................................... - 2.45 ......|..................................................... - 1.84 ......|..................................................... - 1.22 ......|..................................................... - 0.61 :::::||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - -Interface Performance -===================== - -To take a look on the network bandwidth between two nodes, the ``monitor -bandwidth-test`` command is used to run iperf. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test - Possible completions: - accept Wait for bandwidth test connections (port TCP/5001) - initiate Initiate a bandwidth test - -* The ``accept`` command opens a listening iperf server on TCP Port 5001 -* The ``initiate`` command connects to that server to perform the test. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test initiate - Possible completions: - Initiate a bandwidth test to specified host (port TCP/5001) - - - - -Monitor command -=============== - -The ``monitor command`` command allows you to repeatedly run a command to view -a continuously refreshed output. The command is run and output every 2 seconds, -allowing you to monitor the output continuously without having to re-run the -command. This can be useful to follow routing adjacency formation. - -.. code-block:: none - - vyos@router:~$ monitor command "show interfaces" - -Will clear the screen and show you the output of ``show interfaces`` every -2 seconds. - -.. code-block:: none - - Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 - - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.168.1.1/24 u/u - eth0.5 198.51.100.4/24 u/u WAN - lo 127.0.0.1/8 u/u - ::1/128 - vti0 172.25.254.2/30 u/u - vti1 172.25.254.9/30 u/u - -**************** -Terminal/Console -**************** - -Sometimes you need to clear counters or statistics to troubleshoot better. - -To do this use the ``clear`` command in Operational mode. - -to clear the console output - -.. code-block:: none - - vyos@vyos:~$ clear console - -to clear interface counters - -.. code-block:: none - - # clear all interfaces - vyos@vyos:~$ clear interface ethernet counters - # clear specific interface - vyos@vyos:~$ clear interface ehternet eth0 counters - -The command follow the same logic as the ``set`` command in configuration mode. - -.. code-block:: none - - # clear all counters of a interface type - vyos@vyos:~$ clear interface counters - # clear counter of a interface in interface_type - vyos@vyos:~$ clear interface counters - - -to clear counters on firewall rulesets or single rules - -.. code-block:: none - - vyos@vyos:~$ clear firewall name counters - vyos@vyos:~$ clear firewall name rule counters - - vyos@vyos:~$ clear firewall ipv6-name counters - vyos@vyos:~$ clear firewall ipv6-name rule counters - - -****************** -System Information -****************** - -.. _boot-steps: - -Boot Steps -========== - -VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was -the first version of Debian that uses systemd_ as the default init system. - -These are the boot steps for VyOS 1.2 - -1. The BIOS loads Grub (or isolinux for the Live CD) -2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` -3. Kernel Launches Systemd ``/lib/systemd/systemd`` -4. Systemd loads the VyOS service file - ``/lib/systemd/system/vyos-router.service`` -5. The service file launches the VyOS router init script - ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ - Debian package - - 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ - - 2. Initialises the boot configuration file - copies over - ``config.boot.default`` if there is no configuration - 3. Runs the configuration migration, if the configuration is for an older - version of VyOS - 4. Runs The pre-config script, if there is one - ``/config/scripts/vyos-preconfig-bootup.script`` - 5. If the config file was upgraded, runs any post upgrade scripts - ``/config/scripts/post-upgrade.d`` - 6. Starts ``rl-system`` and ``firewall`` - 7. Mounts the ``/boot`` partition - 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ - vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` - - 1. The config loader script writes log entries to - ``/var/log/vyatta-config-loader.log`` - - 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` - 11. Finally it runs the post-config script - ``/config/scripts/vyos-postconfig-bootup.script`` - -.. _Quagga: https://www.quagga.net/ -.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ -.. _FRR: https://frrouting.org/ -.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg -.. _systemd: https://freedesktop.org/wiki/Software/systemd/ -.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst new file mode 100644 index 00000000..0b3420f4 --- /dev/null +++ b/docs/troubleshooting/index.rst @@ -0,0 +1,446 @@ +.. _troubleshooting: + +############### +Troubleshooting +############### + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +****************** +Connectivity Tests +****************** + +Basic Connectivity Tests +======================== + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the :ref:`cli` +section and are omitted from the output here): + +.. opcmd:: ping + + Send ICMP echo requests to destination host. There are multiple options to + ping, inkl. VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + + +.. opcmd:: traceroute + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + + +Advanced Connectivity Tests +=========================== + +.. opcmd:: monitor traceroute + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. + +IPv6 Topology Discovery +======================= + +IPv6 uses different techniques to discover its Neighbors/topology. + +Router Discovery +---------------- + +.. opcmd:: force ipv6-rd interface [address ] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 + +Neighbor Discovery +------------------ + +.. opcmd:: force ipv6-nd interface address + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 + + +*************** +Interface names +*************** + +If you find the names of your interfaces have changed, this could be because your MAC addresses have changed. + +* For example, you have a VyOS VM with 4 Ethernet interfaces named eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + .. code-block:: none + + show interfaces detail + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command specifying the interface name and MAC address you want. + + .. code-block:: none + + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + + If it is a VM, go into the settings of the host and set the MAC address to the settings found in the config.boot file. You can also set the MAC to static if the host allows so. + + +* Another example could be when cloning VyOS VMs in GNS3 and you get into the same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at the configuration file of the cloned machine. They will be correctly regenerated automatically. + + +********** +Monitoring +********** + +VyOS features several monitoring tools. + +.. code-block:: none + + vyos@vyos:~$ monitor + Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service + + +Traffic Dumps +============= + +To monitor interface traffic, issue the :code:`monitor traffic interface ` +command, replacing `` with your chosen interface. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + tcpdump: verbose output suppressed, use -v or -vv for full protocol decode + listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes + 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 + 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 + 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 + 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 + ^C + 4 packets captured + 4 packets received by filter + 0 packets dropped by kernel + vyos@vyos:~$ + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + Possible completions: + Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file + + +Interface Bandwidth Usage +========================= + +to take a quick view on the used bandwidth of an interface use the ``monitor +bandwidth`` command + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth interface eth0 + +show the following: + +.. code-block:: none + + B (RX Bytes/second) + 198.00 .|....|..................................................... + 165.00 .|....|..................................................... + 132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + +Interface Performance +===================== + +To take a look on the network bandwidth between two nodes, the ``monitor +bandwidth-test`` command is used to run iperf. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test + Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test + +* The ``accept`` command opens a listening iperf server on TCP Port 5001 +* The ``initiate`` command connects to that server to perform the test. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test initiate + Possible completions: + Initiate a bandwidth test to specified host (port TCP/5001) + + + + +Monitor command +=============== + +The ``monitor command`` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +.. code-block:: none + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every +2 seconds. + +.. code-block:: none + + Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.168.1.1/24 u/u + eth0.5 198.51.100.4/24 u/u WAN + lo 127.0.0.1/8 u/u + ::1/128 + vti0 172.25.254.2/30 u/u + vti1 172.25.254.9/30 u/u + +**************** +Terminal/Console +**************** + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the ``clear`` command in Operational mode. + +to clear the console output + +.. code-block:: none + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: none + + # clear all interfaces + vyos@vyos:~$ clear interface ethernet counters + # clear specific interface + vyos@vyos:~$ clear interface ehternet eth0 counters + +The command follow the same logic as the ``set`` command in configuration mode. + +.. code-block:: none + + # clear all counters of a interface type + vyos@vyos:~$ clear interface counters + # clear counter of a interface in interface_type + vyos@vyos:~$ clear interface counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: none + + vyos@vyos:~$ clear firewall name counters + vyos@vyos:~$ clear firewall name rule counters + + vyos@vyos:~$ clear firewall ipv6-name counters + vyos@vyos:~$ clear firewall ipv6-name rule counters + + +****************** +System Information +****************** + +.. _boot-steps: + +Boot Steps +========== + +VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was +the first version of Debian that uses systemd_ as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` +3. Kernel Launches Systemd ``/lib/systemd/systemd`` +4. Systemd loads the VyOS service file + ``/lib/systemd/system/vyos-router.service`` +5. The service file launches the VyOS router init script + ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ + Debian package + + 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ + + 2. Initialises the boot configuration file - copies over + ``config.boot.default`` if there is no configuration + 3. Runs the configuration migration, if the configuration is for an older + version of VyOS + 4. Runs The pre-config script, if there is one + ``/config/scripts/vyos-preconfig-bootup.script`` + 5. If the config file was upgraded, runs any post upgrade scripts + ``/config/scripts/post-upgrade.d`` + 6. Starts ``rl-system`` and ``firewall`` + 7. Mounts the ``/boot`` partition + 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ + vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` + + 1. The config loader script writes log entries to + ``/var/log/vyatta-config-loader.log`` + + 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` + 11. Finally it runs the post-config script + ``/config/scripts/vyos-postconfig-bootup.script`` + +.. _Quagga: https://www.quagga.net/ +.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ +.. _FRR: https://frrouting.org/ +.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg +.. _systemd: https://freedesktop.org/wiki/Software/systemd/ +.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html -- cgit v1.2.3