diff options
Diffstat (limited to 'docs/appendix')
| -rw-r--r-- | docs/appendix/commandtree/configmode.rst | 524 | ||||
| -rw-r--r-- | docs/appendix/commandtree/index.rst | 17 | ||||
| -rw-r--r-- | docs/appendix/commandtree/operationmode.rst | 444 | ||||
| -rw-r--r-- | docs/appendix/examples/dmvpn.rst | 105 | ||||
| -rw-r--r-- | docs/appendix/examples/index.rst | 13 | ||||
| -rw-r--r-- | docs/appendix/examples/zone-policy.rst | 379 | ||||
| -rw-r--r-- | docs/appendix/releasenotes.rst | 50 | ||||
| -rw-r--r-- | docs/appendix/troubleshooting.rst | 341 | ||||
| -rw-r--r-- | docs/appendix/vyos-on-baremetal.rst | 72 |
9 files changed, 1945 insertions, 0 deletions
diff --git a/docs/appendix/commandtree/configmode.rst b/docs/appendix/commandtree/configmode.rst new file mode 100644 index 00000000..abb20f98 --- /dev/null +++ b/docs/appendix/commandtree/configmode.rst @@ -0,0 +1,524 @@ +.. _commandtree_configmode: + +Configuration mode +------------------ + +.. code-block:: sh + + confirm Confirm prior commit-confirm + comment Add comment to this configuration element + commit Commit the current set of changes + commit-confirm Commit the current set of changes with 'confirm' required + compare Compare configuration revisions + copy Copy a configuration element + delete Delete a configuration element + discard Discard uncommitted changes + edit Edit a sub-element + exit Exit from this configuration level + load Load configuration from a file and replace running configuration + loadkey Load user SSH key from a file + merge Load configuration from a file and merge running configuration + rename Rename a configuration element + rollback Rollback to a prior config revision (requires reboot) + run Run an operational-mode command + save Save configuration to a file + set Set the value of a parameter or create a new element + show Show the configuration (default values may be suppressed) + + +Confirm +^^^^^^^ + +The ``confirm`` command confirms the prior ``commit-confirm``. + +Comment +^^^^^^^ + +The ``comment`` commands allow you to insert a comment above the current configuration section. +The command cannot be used at the top of the configuration hierarchy, only on subsections. Comments needs to be commited, just like other config changes. + +To add a comment to a section, while being already at the proper section level: + +.. code-block:: sh + + [edit <section>] + vyos@vyos# comment "Type Comment Here" + +To add a comment directly to a section, from the top or a higher section: + +.. code-block:: sh + + [edit] + vyos@vyos# comment <section> "Type Comment Here" + +To remove a comment, add a blank comment to overwrite: + +.. code-block:: sh + + [edit <section>] + vyos@vyos# comment "" + +Examples +******** + +To add a comment to the "interfaces" section: + +.. code-block:: sh + + [edit] + vyos@vyos# edit interfaces + [edit interfaces] + vyos@vyos# comment "Here is a comment" + [edit interfaces] + vyos@vyos# commit + +The comment would then appear like this: + +.. code-block:: sh + + [edit] + vyos@vyos# show + /* Here is a comment */ + interfaces { + ethernet eth0 { + [...] + + +An important thing to note is that since the comment is added on top of the section, it will not appear if the ``show <section>`` command is used. With the above example, the ``show interfaces`` command would return starting after the "interfaces {" line, hiding the comment: + +.. code-block:: sh + + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + [...] + + +To add a comment to the interfaces section from the top: + +.. code-block:: sh + + [edit] + vyos@vyos# comment interfaces "test" + + +The comment can be added to any node that already exists, even if it's multiple levels lower: + +.. code-block:: sh + + [edit] + vyos@vyos# comment interfaces ethernet eth0 vif 222 address "Far down comment" + + +Commit +^^^^^^ + +The ``commit`` command commits the proposed changes to the configuration file. +Every changes done in the configuration session is only applied when the configuration is committed. To view the changes that will be applied, use the show command. +To discard the changes without committing, use the ``discard`` command. The ``commit`` command doesn't save the configuration, you need to manually use the ``save`` command. + +The confirm keyword can be added, see ``commit-confirm``. A comment can be entered, it will appear in the commit log. + +.. code-block:: sh + + [edit] + vyos@vyos# commit + Possible completions: + <Enter> Commit working configuration + comment Comment for commit log + +Commit-confirm +^^^^^^^^^^^^^^ + +The ``commit-confirm`` command commits the proposed changes to the configuration file and starts a timer. +If the ``confirm`` command is not entered before the timer expiration, the configuration will be rolled back and VyOS will reboot. +The default timer value is 10 minutes, but a custom value can be entered. + +.. code-block:: sh + + [edit] + vyos@vyos# commit-confirm + Possible completions: + <Enter> Commit, rollback/reboot in 10 minutes if no confirm + <N> Commit, rollback/reboot in N minutes if no confirm + comment Comment for commit log + + +Compare +^^^^^^^ + +VyOS maintains backups of previous configurations. To compare configuration revisions in configuration mode, use the compare command: + +.. code-block:: sh + + [edit] + vyos@vyos# compare + Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + + Revisions: + 0 2019-03-20 20:57:22 root by boot-config-loader + 1 2019-03-15 20:00:04 root by boot-config-loader + 2 2019-03-05 01:58:39 vyos by cli + 3 2019-03-05 01:54:59 vyos by cli + 4 2019-03-05 01:53:08 vyos by cli + 5 2019-03-05 01:52:21 vyos by cli + 6 2019-02-24 21:01:24 root by boot-config-loader + 7 2019-02-21 22:00:12 vyos by cli + 8 2019-02-21 21:56:49 vyos by cli + + +Copy +^^^^ + +The ``copy`` command allows you to copy a configuration object. + +Copy the configuration entrys from a firewall name WAN rule 1 to rule 2. + +.. code-block:: sh + + [edit firewall name WAN] + vyos@vyos# show + rule 1 { + action accept + source { + address 10.1.0.0/24 + } + } + [edit firewall name WAN] + vyos@vyos# copy rule 1 to rule 2 + [edit firewall name WAN] + vyos@vyos# show + rule 1 { + action accept + source { + address 10.1.0.0/24 + } + } + +rule 2 { + + action accept + + source { + + address 10.1.0.0/24 + + } + +} + +Delete +^^^^^^ + +The ``delte`` command is to delete a configuration entry. + +This Example delete the hole ``service tftp-server`` section. + +.. code-block:: sh + + delete service tftp-server + +Discard +^^^^^^^ + +The ``discard`` command removes all pending configuration changes. + +.. code-block:: sh + + [edit] + vyos@vyos# discard + + Changes have been discarded + +Edit +^^^^ + +The ``edit`` command allows you to navigate down into the configuration tree. +To get back to an upper level, use the ``up`` command or use the ``top`` command to get back to the upper most level. +The ``[edit]`` text displays where the user is located in the configuration tree. + +.. code-block:: sh + + [edit] + vyos@vyos# edit interfaces + [edit interfaces] + vyos@vyos# edit ethernet eth0 + [edit interfaces ethernet eth0] + +Exit +^^^^ + +The ``exit`` command exits the current configuration mode. If the current configuration level isn't the top-most, then the configuration level is put back to the top-most level. +If the configuration level is at the top-most level, then it exits the configuration mode and returns to operational mode. +The ``exit`` command cannot be used if uncommitted changes exists in the configuration file. To exit with uncommitted changes, you either need to use the ``exit discard`` command or you need to commit the changes before exiting. +The ``exit`` command doesn't save the configuration, only the ``save`` command does. A warning will be given when exiting with unsaved changes. Using the ``exit`` command in operational mode will logout the session. + + +Exiting from a configuration level: + + +.. code-block:: sh + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# + +Exiting from configuration mode: + +.. code-block:: sh + + [edit] + vyos@vyos# exit + exit + vyos@vyos:~$ + +Exiting from operational mode: + +.. code-block:: sh + + vyos@vyos:~$ exit + logout + +Error message when trying to exit with uncommitted changes: + +.. code-block:: sh + + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# + + +Warning message when exiting with unsaved changes: + +.. code-block:: sh + + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + exit + vyos@vyos:~$ + +Load +^^^^ + +The ``load`` command load a configuration from a local or remote file. You have to be use ``commit`` to make the change active + +.. code-block:: sh + + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + + +.. code-block:: sh + + [edit] + vyos@vyos# load + Loading configuration from '/config/config.boot'... + + Load complete. Use 'commit' to make changes active. + + +Loadkey +^^^^^^^^ + +Copies the content of a public key to the ~/.ssh/authorized_keys file. + +.. code-block:: sh + + loadkey <username> [tab] + + <file> Load from file on local machine + scp://<user>@<host>/<file> Load from file on remote machine + sftp://<user>@<host>/<file> Load from file on remote machine + ftp://<user>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + +Merge +^^^^^ + +The ``merge`` command merge the config from a local or remote file with the running config. + +In the example below exist a ``default-firewall.config`` file with some common firewall rules you saved earlier. + +.. code-block:: sh + + [edit] + vyos@vyos# show firewall + Configuration under specified path is empty + [edit] + vyos@vyos# merge default-firewall.config + Loading configuration from '/config/default-firewall.config'... + + Merge complete. Use 'commit' to make changes active. + [edit] + vyos@vyos# + + vyos@vyos# show firewall + +all-ping enable + +broadcast-ping disable + +config-trap disable + +ipv6-receive-redirects disable + +ipv6-src-route disable + +ip-src-route disable + +log-martians enable + +name WAN { + + default-action drop + + rule 1 { + + action accept + + source { + + address 10.1.0.0/24 + + } + + } + + rule 2 { + + action accept + + source { + + address 10.1.0.0/24 + + } + ...... + + +Rename +^^^^^^ + +The ``rename`` command allows you to rename or move a configuration object. + +See here how to move the configuration entrys from vlanid 3 to 2 + +.. code-block:: sh + + [edit interfaces ethernet eth1] + vyos@vyos# show + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + vif 3 { + address 10.4.4.4/32 + } + [edit interfaces ethernet eth1] + vyos@vyos# rename vif 3 to vif 2 + [edit interfaces ethernet eth1] + vyos@vyos# show + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + +vif 2 { + + address 10.4.4.4/32 + +} + -vif 3 { + - address 10.4.4.4/32 + -} + [edit interfaces ethernet eth1] + vyos@vyos# + + +Rollback +^^^^^^^^ + +You can ``rollback`` configuration using the rollback command, however this command will currently trigger a system reboot. +Use the compare command to verify the configuration you want to rollback to. + +.. code-block:: sh + + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2018): + + The system is going down for reboot NOW! + [edit] + vyos@vyos# + +Run +^^^ + +The ``run`` command allows you to execute any operational mode commands without exiting the configuration session. + +.. code-block:: sh + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 10.1.1.1/24 u/u + + +Save +^^^^ + +The ``save`` command saves the current configuration to non-volatile storage. VyOS also supports saving and loading configuration remotely using SCP, FTP, or TFTP. + +.. code-block:: sh + + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>/<file> Save to file on remote machine + sftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine + +Set +^^^ + +The ``set`` command create all configuration entrys + +.. code-block:: sh + + [edit] + vyos@vyos# set protocols static route 0.0.0.0/0 next-hop 192.168.1.1 + +Show +^^^^ + +The ``show`` command in the configuration mode displays the configuration and show uncommitted changes. + +Show the hole config, the address and description of eth1 is moving to vlan 2 if you commit the changes. + +.. code-block:: sh + + [edit] + vyos@vyos# show + interfaces { + dummy dum0 { + address 10.3.3.3/24 + } + ethernet eth0 { + address dhcp + duplex auto + hw-id 08:00:27:2b:c0:0b + smp-affinity auto + speed auto + } + ethernet eth1 { + - address 10.1.1.1/32 + - description "MGMT Interface" + duplex auto + hw-id 08:00:27:81:c6:59 + smp-affinity auto + speed auto + + vif 2 { + + address 10.1.1.1/32 + + description "MGMT Interface" + + } + } + loopback lo { + } + } + service { + ssh { + port 22 + ......
\ No newline at end of file diff --git a/docs/appendix/commandtree/index.rst b/docs/appendix/commandtree/index.rst new file mode 100644 index 00000000..c3bca008 --- /dev/null +++ b/docs/appendix/commandtree/index.rst @@ -0,0 +1,17 @@ +.. _commandtree: + +Command tree +============ + +See the the full Command tree in Operational mode and Configuration mode + + + +.. toctree:: + :maxdepth: 2 + :hidden: + + + operationmode + configmode + diff --git a/docs/appendix/commandtree/operationmode.rst b/docs/appendix/commandtree/operationmode.rst new file mode 100644 index 00000000..487df032 --- /dev/null +++ b/docs/appendix/commandtree/operationmode.rst @@ -0,0 +1,444 @@ +.. _commandtree_operationmode: + +Operational mode +---------------- + +Operational mode allows for commands to perform operational system tasks and view system and service status. +After this is the first view after the login. +Please see :ref:`cli` for navigation in the CLI + + +.. code-block:: sh + + + vyos@vyos:~$ [tab] + Possible completions: + add Add an object to a service + clear Clear system information + clone Clone an object + configure Enter configure mode + connect Establish a connection + copy Copy an object + delete Delete an object + disconnect Take down a connection + force Force an operation + format Format a device + generate Generate an object + install Install a new system + monitor Monitor system information + ping Send IPv4 or IPv6 ICMP (Internet Control Message Protocol) echo requests + poweroff Poweroff the system + reboot Reboot the system + release Release specified variable + rename Rename an object + renew Renew specified variable + reset Reset a service + restart Restart a service + set Set operational options + show Show system information + telnet Telnet to a node + traceroute Track network path to node + update Update data for a service + + +Add +^^^ + +.. code-block:: sh + + raid Add a RAID set element + system Add an item to a system facility + +Clear +^^^^^ + +.. code-block:: sh + + console Clear screen + firewall Clear firewall statistics + flow-accounting Clear flow accounting + interfaces Clear interface information + ip Clear Internet Protocol (IP) statistics or status + ipv6 Clear Internet Protocol (IPv6) statistics or status + nat Clear network address translation (NAT) tables + policy Clear policy statistics + + +Clone +^^^^^ +The ``clone`` command allows you to clone a configuration from a system image to another one, or from the running config to another system image. +To clone the running config to a system image: + +.. code-block:: sh + + clone system config <system-image> from running + +To clone from system image A to system image B: + +.. code-block:: sh + + clone system config <system-image-B> from <system-image-A> + + +Configure +^^^^^^^^^ + +The ``configure`` command allows you to enter configuration mode. + +.. code-block:: sh + + vyos@vyos:~$ configure + [edit] + vyos@vyos# + + +Connect +^^^^^^^ + +The ``connect`` command allows you to bring up a connection oriented interface, like a pppoe interface. + +.. code-block:: sh + + connect interface <interface> + +Copy +^^^^ + +The ``copy`` command allows you to copy a file to your running config or over images. + +It can look like this example: + +.. code-block:: sh + + vyos@vyos:~$ copy file [tab] + Possible completions: + http://<user>:<passwd>@<host>/<file> + Copy files from specified source + scp://<user>:<passwd>@<host>/<file> + ftp://<user>:<passwd>@<host>/<file> + tftp://<host>/<file> + 1.2.0://config/ + 1.2.0-rolling+201902251818://config/ + 1.2.0-rolling+201902201040://config/ + 1.2.0-rolling+201902080337://config/ + 1.2.0-H4://config/ + running://config/ + + +To copy from file A to file B: + +.. code-block:: sh + + copy <file A> to <file B> + + +Delete +^^^^^^ + +.. code-block:: sh + + conntrack Delete Conntrack entries + file Delete files in a particular image + log Delete a log file + raid Remove a RAID set element + system Delete system objects + + +Disconnect +^^^^^^^^^^ + +The ``disconnect`` command allows you to take down a connection oriented interface, like a pppoe interface. + +.. code-block:: sh + + disconnect interface <interface> + +Force +^^^^^ + +.. code-block:: sh + + arp Send gratuitous ARP request or reply + cluster Force a cluster state transition + + +Format +^^^^^^ + +The ``format`` command allows you to format a disk the same way as another one. + +.. code-block:: sh + + format disk <target> like <source> + +Generate +^^^^^^^^ + +.. code-block:: sh + + openvpn OpenVPN key generation tool + ssh-server-key + Regenerate the host SSH keys and restart the SSH server + tech-support Generate tech-support archive + vpn VPN key generation utility + wireguard wireguard key generation utility + +Install +^^^^^^^ + +The ``install`` command allows you to install the system image on the disk. + +.. code-block:: sh + + install image + + +Monitor +^^^^^^^ + +``monitor`` can be used to continually view what is happening on the router. + +.. code-block:: sh + + 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) + 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 + + +Ping +^^^^ + +The ``ping`` command allows you to send an ICMP-EchoRequest packet and display the ICMP-EchoReply received. + +.. code-block:: sh + + <hostname> Send Internet Control Message Protocol (ICMP) echo request + <x.x.x.x> + <h:h:h:h:h:h:h:h> + + +Poweroff +^^^^^^^^ + +The ``poweroff`` command allows you to properly shut down the VyOS instance. Without any modifier, the command is executed immediately. + +.. code-block:: sh + + <Enter> Execute the current command + at Poweroff at a specific time + cancel Cancel a pending poweroff + in Poweroff in X minutes + now Poweroff the system without confirmation + +Reboot +^^^^^^ +The ``reboot`` command allows you to properly restart the VyOS instance. Without any modifier, the command is executed immediately. + +.. code-block:: sh + + <Enter> Execute the current command + at Poweroff at a specific time + cancel Cancel a pending poweroff + in Poweroff in X minutes + now Poweroff the system without confirmation + +Release +^^^^^^^ + +The ``release`` command allows you to release a DHCP or DHCPv6 lease. + +.. code-block:: sh + + vyos@vyos:~$ release dhcp interface <int> + vyos@vyos:~$ release dhcpv6 interface <int> + + +Rename +^^^^^^ + +The ``rename`` command allows you to rename a system image. + +.. code-block:: sh + + rename system image <currentname> <newname> + + +Renew +^^^^^ + +The ``renew`` command allows you to renew a DHCP or DHCPv6 lease. + +.. code-block:: sh + + vyos@vyos:~$ renew dhcp interface <int> + vyos@vyos:~$ renew dhcpv6 interface <int> + +Reset +^^^^^ + +.. code-block:: sh + + conntrack Reset all currently tracked connections + conntrack-sync + Reset connection syncing parameters + dns Reset a DNS service state + firewall reset a firewall group + ip Reset Internet Protocol (IP) parameters + ipv6 Reset Internet Protocol version 6 (IPv6) parameters + nhrp Clear/Purge NHRP entries + openvpn Reset OpenVPN + terminal Reset terminal + vpn Reset Virtual Private Network (VPN) information + +Restart +^^^^^^^ + +.. code-block:: sh + + cluster Restart cluster node + conntrack-sync + Restart connection tracking synchronization service + dhcp Restart DHCP processes + dhcpv6 Restart DHCPv6 processes + dns Restart a DNS service + flow-accounting + Restart flow-accounting service + https Restart https server + vpn Restart IPsec VPN + vrrp Restart the VRRP (Virtual Router Redundancy Protocol) process + wan-load-balance + Restart WAN load balancing + webproxy Restart webproxy service + +Set +^^^ + +.. code-block:: sh + + <OPTION> Bash builtin set command + console Control console behaviors + date Set system date and time + system Set system operational parameters + terminal Control terminal behaviors + +Show +^^^^ + +.. code-block:: sh + + arp Show Address Resolution Protocol (ARP) information + bridge Show bridging information + cluster Show clustering information + configuration Show available saved configurations + conntrack Show conntrack entries in the conntrack table + conntrack-sync + Show connection syncing information + date Show system time and date + dhcp Show DHCP (Dynamic Host Configuration Protocol) information + dhcpv6 Show DHCPv6 (IPv6 Dynamic Host Configuration Protocol) information + disk Show status of disk device + dns Show DNS information + file Show files for a particular image + firewall Show firewall information + flow-accounting + Show flow accounting statistics + hardware Show system hardware details + history show command history + host Show host information + incoming Show ethernet input-policy information + interfaces Show network interface information + ip Show IPv4 routing information + ipv6 Show IPv6 routing information + license Show VyOS license information + lldp Show lldp + log Show contents of current master log file + login Show current login credentials + monitoring Show currently monitored services + nat Show Network Address Translation (NAT) information + nhrp Show NHRP info + ntp Show peer status of NTP daemon + openvpn Show OpenVPN information + policy Show policy information + poweroff Show scheduled poweroff + pppoe-server show pppoe-server status + queueing Show ethernet queueing information + raid Show statis of RAID set + reboot Show scheduled reboot + remote-config Show remote side config + route-map Show route-map information + snmp Show status of SNMP on localhost + system Show system information + system-integrity + checks the integrity of the system + table Show routing table + tech-support Show consolidated tech-support report (private information removed) + users Show user information + version Show system version information + vpn Show Virtual Private Network (VPN) information + vrrp Show VRRP (Virtual Router Redundancy Protocol) information + wan-load-balance + Show Wide Area Network (WAN) load-balancing information + webproxy Show webproxy information + wireguard Show wireguard properties + zone-policy Show summary of zone policy for a specific zone + +Telnet +^^^^^^ +In the past the ``telnet`` command allowed you to connect remotely to another device using the telnet protocol. +Telnet is unencrypted and should not use anymore. But its nice to test if an TCP Port to a host is open. + + +.. code-block:: sh + + vyos@vyos:~$ telnet 192.168.1.3 443 + Trying 192.168.1.3... + telnet: Unable to connect to remote host: Network is unreachable + + vyos@vyos:~$ telnet 192.168.1.4 443 + Trying 192.168.1.4... + Connected to 192.168.1.4. + Escape character is '^]'. + +Traceroute +^^^^^^^^^^ + +The ``traceroute`` command allows you to trace the path taken to a particular device. + +.. code-block:: sh + + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> + + +Update +^^^^^^ + +.. code-block:: sh + + dns Update DNS information + webproxy Update webproxy
\ No newline at end of file diff --git a/docs/appendix/examples/dmvpn.rst b/docs/appendix/examples/dmvpn.rst new file mode 100644 index 00000000..d3bf45c7 --- /dev/null +++ b/docs/appendix/examples/dmvpn.rst @@ -0,0 +1,105 @@ + +.. _examples-dmvpn: + +VyOS DMVPN Hub +-------------- + +General infomration can be found in the :ref:`vpn-dmvpn` chapter. + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: sh + + set interfaces tunnel tun100 address '172.16.253.134/29' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '11.22.33.44' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication '<nhrp secret key>' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 multicast 'dynamic' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'tunnel' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret '<secretkey>' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + +Cisco IOS Spoke +^^^^^^^^^^^^^^^ + +This example is verified with a Cisco 2811 platform running IOS 15.1(4)M9 and +VyOS 1.1.7 (helium) up to VyOS 1.2 (Crux). + +.. code-block:: sh + + Cisco IOS Software, 2800 Software (C2800NM-ADVENTERPRISEK9-M), Version 15.1(4)M9, RELEASE SOFTWARE (fc3) + Technical Support: http://www.cisco.com/techsupport + Copyright (c) 1986-2014 by Cisco Systems, Inc. + Compiled Fri 12-Sep-14 10:45 by prod_rel_team + + ROM: System Bootstrap, Version 12.3(8r)T7, RELEASE SOFTWARE (fc1) + +Use this configuration on your Cisco device: + +.. code-block:: sh + + crypto pki token default removal timeout 0 + crypto keyring DMVPN + pre-shared-key address 1.2.3.4 key <secretkey> + ! + crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + ! + crypto isakmp invalid-spi-recovery + crypto isakmp keepalive 30 30 periodic + crypto isakmp profile DMVPN + keyring DMVPN + match identity address 11.22.33.44 255.255.255.255 + ! + crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport + ! + crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + ! + interface Tunnel10 + description Tunnel to DMVPN HUB + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication <nhrp secret key> + ip nhrp map multicast 11.22.33.44 + ip nhrp map 172.16.253.134 11.22.33.44 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source Dialer1 + tunnel mode gre multipoint + tunnel key 1 diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst new file mode 100644 index 00000000..c6e10eeb --- /dev/null +++ b/docs/appendix/examples/index.rst @@ -0,0 +1,13 @@ +.. _examples: + +Configuration Examples +====================== + +This chapter contains various configuration Examples + + +.. toctree:: + :maxdepth: 2 + + dmvpn + zone-policy diff --git a/docs/appendix/examples/zone-policy.rst b/docs/appendix/examples/zone-policy.rst new file mode 100644 index 00000000..d159d02d --- /dev/null +++ b/docs/appendix/examples/zone-policy.rst @@ -0,0 +1,379 @@ +.. _examples-zone-policy: + +Zone-Policy example +------------------- + +Native IPv4 and IPv6 +^^^^^^^^^^^^^^^^^^^^ + +We have three networks. + +.. code-block:: sh + + WAN - 172.16.10.0/24, 2001:0DB8:0:9999::0/64 + LAN - 192.168.100.0/24, 2001:0DB8:0:AAAA::0/64 + DMZ - 192.168.200.0/24, 2001:0DB8:0:BBBB::0/64 + + +This specific example is for a router on a stick, but is very easily adapted +for however many NICs you have. + +[http://imgur.com/Alz1J.png Topology Image] + +The VyOS interface is assigned the .1/:1 address of their respective networks. +WAN is on VLAN 10, LAN on VLAN 20, and DMZ on VLAN 30. + +It will look something like this: + +.. code-block:: sh + + interfaces { + ethernet eth0 { + duplex auto + hw-id 00:0c:29:6e:2a:92 + smp_affinity auto + speed auto + vif 10 { + address 172.16.10.1/24 + address 2001:db8:0:9999::1/64 + } + vif 20 { + address 192.168.100.1/24 + address 2001:db8:0:AAAA::1/64 + } + vif 30 { + address 192.168.200.1/24 + address 2001:db8:0:BBBB::1/64 + } + } + loopback lo { + } + } + + +Zones Basics +^^^^^^^^^^^^ + +Each interface is assigned to a zone. The interface can be physical or virtual +such as tunnels (VPN, pptp, gre, etc) and are treated exactly the same. + +Traffic flows from zone A to zone B. That flow is what I refer to as a +zone-pair-direction. eg. A->B and B->A are two zone-pair-destinations. + +Ruleset are created per zone-pair-direction. + +I name rule sets to indicate which zone-pair-direction they represent. eg. +ZoneA-ZoneB or ZoneB-ZoneA. LAN-DMZ, DMZ-LAN. + +In VyOS, you have to have unique Ruleset names. In the event of overlap, I +add a "-6" to the end of v6 rulesets. eg. LAN-DMZ, LAN-DMZ-6. This allows for +each auto-completion and uniqueness. + +In this example we have 4 zones. LAN, WAN, DMZ, Local. The local zone is the +firewall itself. + +If your computer is on the LAN and you need to SSH into your VyOS box, you +would need a rule to allow it in the LAN-Local ruleset. If you want to access +a webpage from your VyOS box, you need a rule to allow it in the Local-LAN +ruleset. + +In rules, it is good to keep them named consistently. As the number of rules +you have grows, the more consistency you have, the easier your life will be. + +.. code-block:: sh + + Rule 1 - State Established, Related + Rule 2 - State Invalid + Rule 100 - ICMP + Rule 200 - Web + Rule 300 - FTP + Rule 400 - NTP + Rule 500 - SMTP + Rule 600 - DNS + Rule 700 - DHCP + Rule 800 - SSH + Rule 900 - IMAPS + +The first two rules are to deal with the idiosyncrasies of VyOS and iptables. + +Zones and Rulesets both have a default action statement. When using +Zone-Policies, the default action is set by the zone-policy statement and is +represented by rule 10000. + +It is good practice to log both accepted and denied traffic. It can save you +significant headaches when trying to troubleshoot a connectivity issue. + +To add logging to the default rule, do: + +.. code-block:: sh + + set firewall name <ruleSet> enable-default-log + + +By default, iptables does not allow traffic for established session to return, +so you must explicitly allow this. I do this by adding two rules to every +ruleset. 1 allows established and related state packets through and rule 2 +drops and logs invalid state packets. We place the established/related rule at +the top because the vast majority of traffic on a network is established and +the invalid rule to prevent invalid state packets from mistakenly being matched +against other rules. Having the most matched rule listed first reduces CPU load +in high volume environments. Note: I have filed a bug to have this added as a +default action as well. + +''It is important to note, that you do not want to add logging to the +established state rule as you will be logging both the inbound and outbound +packets for each session instead of just the initiation of the session. +Your logs will be massive in a very short period of time.'' + +In VyOS you must have the interfaces created before you can apply it to the +zone and the rulesets must be created prior to applying it to a zone-policy. + +I create/configure the interfaces first. Build out the rulesets for each +zone-pair-direction which includes at least the three state rules. Then I setup +the zone-policies. + +Zones do not allow for a default action of accept; either drop or reject. +It is important to remember this because if you apply an interface to a zone +and commit, any active connections will be dropped. Specifically, if you are +SSH’d into VyOS and add local or the interface you are connecting through to a +zone and do not have rulesets in place to allow SSH and established sessions, +you will not be able to connect. + +The following are the rules that were created for this example +(may not be complete), both in IPv4 and IPv6. If there is no IP specified, +then the source/destination address is not explicit. + +.. code-block:: sh + + WAN – DMZ:192.168.200.200 – tcp/80 + WAN – DMZ:192.168.200.200 – tcp/443 + WAN – DMZ:192.168.200.200 – tcp/25 + WAN – DMZ:192.168.200.200 – tcp/53 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/80 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/443 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/25 + WAN – DMZ:2001:0DB8:0:BBBB::200 – tcp/53 + + DMZ - Local - tcp/53 + DMZ - Local - tcp/123 + DMZ - Local - tcp/67,68 + + LAN - Local - tcp/53 + LAN - Local - tcp/123 + LAN - Local - tcp/67,68 + LAN:192.168.100.10 - Local - tcp/22 + LAN:2001:0DB8:0:AAAA::10 - Local - tcp/22 + + LAN - WAN - tcp/80 + LAN - WAN - tcp/443 + LAN - WAN - tcp/22 + LAN - WAN - tcp/20,21 + + DMZ - WAN - tcp/80 + DMZ - WAN - tcp/443 + DMZ - WAN - tcp/22 + DMZ - WAN - tcp/20,21 + DMZ - WAN - tcp/53 + DMZ - WAN - udp/53 + + Local - WAN - tcp/80 + Local - WAN - tcp/443 + Local - WAN - tcp/20,21 + + Local - DMZ - tcp/25 + Local - DMZ - tcp/67,68 + Local - DMZ - tcp/53 + Local - DMZ - udp/53 + + Local - LAN - tcp/67,68 + + LAN - DMZ - tcp/80 + LAN - DMZ - tcp/443 + LAN - DMZ - tcp/993 + LAN:2001:0DB8:0:AAAA::10 - DMZ:2001:0DB8:0:BBBB::200 - tcp/22 + LAN:192.168.100.10 - DMZ:192.168.200.200 - tcp/22 + +Since we have 4 zones, we need to setup the following rulesets. + +.. code-block:: sh + + Lan-wan + Lan-local + Lan-dmz + Wan-lan + Wan-local + Wan-dmz + Local-lan + Local-wan + Local-dmz + Dmz-lan + Dmz-wan + Dmz-local + +Even if the two zones will never communicate, it is a good idea to create the +zone-pair-direction rulesets and set enable-default-log. This will allow you to +log attempts to access the networks. Without it, you will never see the +connection attempts. + +This is an example of the three base rules. + +.. code-block:: sh + + name wan-lan { + default-action drop + enable-default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + } + } + + +Here is an example of an IPv6 DMZ-WAN ruleset. + +.. code-block:: sh + + ipv6-name dmz-wan-6 { + default-action drop + enable-default-log + rule 1 { + action accept + state { + established enable + related enable + } + } + rule 2 { + action drop + log enable + state { + invalid enable + } + rule 100 { + action accept + log enable + protocol ipv6-icmp + } + rule 200 { + action accept + destination { + port 80,443 + } + log enable + protocol tcp + } + rule 300 { + action accept + destination { + port 20,21 + } + log enable + protocol tcp + } + rule 500 { + action accept + destination { + port 25 + } + log enable + protocol tcp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 600 { + action accept + destination { + port 53 + } + log enable + protocol tcp_udp + source { + address 2001:db8:0:BBBB::200 + } + } + rule 800 { + action accept + destination { + port 22 + } + log enable + protocol tcp + } + } + +Once you have all of your rulesets built, then you need to create your +zone-policy. + +Start by setting the interface and default action for each zone. + +.. code-block:: sh + + set zone-policy zone dmz default-action drop + set zone-policy zone dmz interface eth0.30 + +In this case, we are setting the v6 ruleset that represents traffic sourced +from the LAN, destined for the DMZ. +Because the zone-policy firewall syntax is a little awkward, I keep it straight +by thinking of it backwards. + + set zone-policy zone dmz from lan firewall ipv6-name lan-dmz-6 + +dmz-lan policy is lan-dmz. You can get a rhythm to it when you build out a bunch at one time. + +In the end, you will end up with something like this config. I took out everything but the Firewall, Interfaces, and zone-policy sections. It is long enough as is. +== IPv6 Tunnel == + +If you are using a IPv6 tunnel from HE.net or someone else, the basis is the same except you have two WAN interface. One for v4 and one for v6. + +You would have 5 zones instead of just 4 and you would configure your v6 ruleset between your tunnel interface and your LAN/DMZ zones instead of to the WAN. + +LAN, WAN, DMZ, local and TUN (tunnel) + +v6 pairs would be: + +.. code-block:: sh + + lan-tun + lan-local + lan-dmz + tun-lan + tun-local + tun-dmz + local-lan + local-tun + local-dmz + dmz-lan + dmz-tun + dmz-local + +Notice, none go to WAN since WAN wouldn't have a v6 address on it. + +You would have to add a couple of rules on your wan-local ruleset to allow protocol 41 in. + +Something like: + +.. code-block:: sh + + rule 400 { + action accept + destination { + address 172.16.10.1 + } + log enable + protocol 41 + source { + address ip.of.tunnel.broker + } + } + diff --git a/docs/appendix/releasenotes.rst b/docs/appendix/releasenotes.rst new file mode 100644 index 00000000..a2d9616e --- /dev/null +++ b/docs/appendix/releasenotes.rst @@ -0,0 +1,50 @@ +.. _releasenotes: + +Release notes +############# + +1.2 (Crux) +========== + +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. +* 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 (`T1326 <https://phabricator.vyos.net/T1326>`_). +* The collection of network card firmware is now much more extensive. +* VRRP now correctly uses a virtual rather than physical MAC addresses in the RFC-compliant mode (`T1271 <https://phabricator.vyos.net/T1271>`_). +* DHCP WPAD URL option works correctly again (`T1330 <https://phabricator.vyos.net/T1330>`_) +* Many to many NAT rules now can use source/destination and translation networks of non-matching size (`T1312 <https://phabricator.vyos.net/T1312>`_). If 1:1 network bits translation is desired, it’s now user’s responsibility to check if prefix length matches. +* IPv6 network prefix translation is fixed (`T1290 <https://phabricator.vyos.net/T1290>`_). +* Non-alphanumeric characters such as “>” can now be safely used in PPPoE passwords (`T1308 <https://phabricator.vyos.net/T1308>`_). +* “show | commands” no longer fails when a config section ends with a leaf node such as “timezone” in “show system | commands” (`T1305 <https://phabricator.vyos.net/T1305>`_). +* “show | commands” correctly works in config mode now (`T1235 <https://phabricator.vyos.net/T1235>`_). +* VTI is now compatible with the DHCP-interface IPsec option (`T1298 <https://phabricator.vyos.net/T1298>`_). +* “show dhcp server statistics” command was broken in latest Crux (`T1277 <https://phabricator.vyos.net/T1277>`_). +* An issue with TFTP server refusing to listen on addresses other than loopback was fixed (`T1261 <https://phabricator.vyos.net/T1261>`_). +* Template issue that might cause UDP broadcast relay fail to start is fixed (`T1224 <https://phabricator.vyos.net/T1224>`_). +* VXLAN value validation is improved (`T1067 <https://phabricator.vyos.net/T1067>`_). +* Blank hostnames in DHCP updates no longer can crash DNS forwarding (`T1211 <https://phabricator.vyos.net/T1211>`_). +* Correct configuration is now generated for DHCPv6 relays with more than one upstream interface (`T1322 <https://phabricator.vyos.net/T1322>`_). +* “relay-agents-packets” option works correctly now (`T1234 <https://phabricator.vyos.net/T1234>`_). +* Dynamic DNS data is now cleaned on configuration change (`T1231 <https://phabricator.vyos.net/T1231>`_). +* Remote Syslog can now use a fully qualified domain name (`T1282 <https://phabricator.vyos.net/T1282>`_). +* ACPI power off works again (`T1279 <https://phabricator.vyos.net/T1279>`_). +* Negation in WAN load balancing rules works again (`T1247 <https://phabricator.vyos.net/T1247>`_). +* FRR’s staticd now starts on boot correctly (`T1218 <https://phabricator.vyos.net/T1218>`_). +* The installer now correctly detects SD card devices (`T1296 <https://phabricator.vyos.net/T1296>`_). +* Wireguard peers can be disabled now (`T1225 <https://phabricator.vyos.net/T1225>`_). +* The issue with wireguard interfaces impossible to delete is fixed (`T1217 <https://phabricator.vyos.net/T1217>`_). +* Unintended IPv6 access is fixed in SNMP configuration (`T1160 <https://phabricator.vyos.net/T1160>`_). +* It’s now possible to exclude hosts from the transparent web proxy (`T1060 <https://phabricator.vyos.net/T1060>`_). +* An issue with rules impossible to delete from the zone-based firewall is fixed (`T484 <https://phabricator.vyos.net/T484>`_). + +Earlier releases +================ + +See `the wiki <https://wiki.vyos.net/wiki/1.2.0/release_notes>`_. diff --git a/docs/appendix/troubleshooting.rst b/docs/appendix/troubleshooting.rst new file mode 100644 index 00000000..e5b9b7a9 --- /dev/null +++ b/docs/appendix/troubleshooting.rst @@ -0,0 +1,341 @@ +.. _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. + +Basic Connectivity Verification +------------------------------- + +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): + +.. code-block:: sh + + vyos@vyos:~$ ping + Possible completions: + <hostname> Send Internet Control Message Protocol (ICMP) echo request + <x.x.x.x> + <h:h:h:h:h:h:h:h> + +Several options are available when more extensive troubleshooting is needed: + +.. code-block:: sh + + vyos@vyos:~$ ping 8.8.8.8 + Possible completions: + <Enter> 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 + +.. code-block:: sh + + vyos@vyos:~$ traceroute + Possible completions: + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> + +However, another tool, mtr_, is available which combines ping and traceroute +into a single tool. An example of its output is shown: + +.. code-block:: sh + + 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 of ``mtr`` 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. + +Monitoring +---------- + +Network Interfaces +^^^^^^^^^^^^^^^^^^ + +It's possible to monitor network traffic, either at the flow level or protocol +level. This can be useful when troubleshooting a variety of protocols and +configurations. The following interface types can be monitored: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces + Possible completions: + <Enter> Execute the current command + bonding Monitor a bonding interface + bridge Monitor a bridge interface + ethernet Monitor a ethernet interface + loopback Monitor a loopback interface + openvpn Monitor an openvpn interface + pppoe Monitor pppoe interface + pseudo-ethernet + Monitor a pseudo-ethernet interface + tunnel Monitor a tunnel interface + vrrp Monitor a vrrp interface + vti Monitor a vti interface + wireless Monitor wireless interface + +To monitor traffic flows, issue the :code:`monitor interfaces <type> <name> flow` +command, replacing `<type>` and `<name>` with your desired interface type and +name, respectively. Output looks like the following: + +.. code-block:: sh + + 12.5Kb 25.0Kb 37.5Kb 50.0Kb 62.5Kb + ???????????????????????????????????????????????????????????????????????????????????????????????????? + 10.11.111.255 => 10.11.110.37 0b 0b 0b + <= 624b 749b 749b + 10.11.110.29 => 10.62.200.11 0b 198b 198b + <= 0b 356b 356b + 255.255.255.255 => 10.11.110.47 0b 0b 0b + <= 724b 145b 145b + 10.11.111.255 => 10.11.110.47 0b 0b 0b + <= 724b 145b 145b + 10.11.111.255 => 10.11.110.255 0b 0b 0b + <= 680b 136b 136b + ???????????????????????????????????????????????????????????????????????????????????????????????????? + TX: cumm: 26.7KB peak: 40.6Kb rates: 23.2Kb 21.4Kb 21.4Kb + RX: 67.5KB 63.6Kb 54.6Kb 54.0Kb 54.0Kb + TOTAL: 94.2KB 104Kb 77.8Kb 75.4Kb 75.4Kb + +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. + +To monitor interface traffic, issue the :code:`monitor interfaces <type> <name> +traffic` command, replacing `<type>` and `<name>` with your desired interface +type and name, respectively. This command invokes the familiar tshark_ utility +and the following options are available: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces ethernet eth0 traffic + Possible completions: + <Enter> Execute the current command + detail Monitor detailed traffic for the specified ethernet interface + filter Monitor filtered traffic for the specified ethernet interface + save Save monitored traffic to a file + unlimited Monitor traffic for the specified ethernet interface + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. The `detail` keyword provides verbose output of the traffic seen on +the monitored interface. The `filter` keyword accepts valid `PCAP filter +expressions`_, enclosed in single or double quotes (e.g. "port 25" or "port 161 +and udp"). The `save` keyword allows you to save the traffic dump to a file. +The `unlimited` keyword is used to specify that an unlimited number of packets +can be captured (by default, 1,000 packets are captured and you're returned to +the VyOS command prompt). + +Interface Bandwith +^^^^^^^^^^^^^^^^^^ + +to take a quick view on the used bandwith of an interface use the ``monitor bandwith`` command + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth interface eth0 + +show the following: + +.. code-block:: sh + + eth0 bmon 3.5 + Interfaces │ RX bps pps %│ TX bps pps % + >eth0 │ 141B 2 │ 272B 1 + ───────────────────────────────┴───────────────────────┴──────────────────────────────────────────────────────────────── + 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 + + ───────────────────────────────────────── Press d to enable detailed statistics ──────────────────────────────────────── + ─────────────────────────────────────── Press i to enable additional information ─────────────────────────────────────── + Wed Apr 3 14:46:59 2019 Press ? for help + +| Press ``d`` for more detailed informations or ``i`` for additional information. +| To exit press ``q`` and than ``y`` + +Interface performance +^^^^^^^^^^^^^^^^^^^^^ + +To take a look on the network bandwith between two nodes, the ``monitor bandwidth-test`` command is used to run iperf. + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth-test + Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test + +| The ``accept`` command open a listen iperf server on TCP Port 5001 +| The ``initiate`` command conncet to this server. + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth-test initiate + Possible completions: + <hostname> Initiate a bandwidth test to specified host (port TCP/5001) + <x.x.x.x> + <h:h:h:h:h:h:h:h> + + +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:: sh + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every 2 seconds. + +.. code-block:: sh + + Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper s... 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.32.254.2/30 u/u + vti1 172.32.254.9/30 u/u + +Clear Command +------------- + +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:: sh + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: sh + + # 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:: sh + + # clear all counters of a interface type + vyos@vyos:~$ clear interface <interface_type> counters + # clear counter of a interface in interface_type + vyos@vyos:~$ clear interface <interface_type> <interace_name> counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: sh + + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters + + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters + + +Basic System Information +------------------------ + +Boot steps +^^^^^^^^^^ + +VyOS 1.2.0+ 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.0+ + +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: http://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/ +.. _mtr: http://www.bitwizard.nl/mtr/ +.. _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/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst new file mode 100644 index 00000000..bda81116 --- /dev/null +++ b/docs/appendix/vyos-on-baremetal.rst @@ -0,0 +1,72 @@ +.. _vyosonbaremetal: + +Running on Bare Metal +##################### + +Intel Atom C3000 +**************** + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +Shopping Card +------------- + +* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN with + Intel C3000 SoC 1GbE) +* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +* 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +Optional (10GE) +--------------- +If you wan't to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +* 1x Supermicro RSC-RR1U-E8 (Riser Card) +* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no information +about [OpenBMC](https://www.openbmc.org/)) so far on this motherboard. + +Pictures +-------- + +.. figure:: /_static/images/1u_vyos_back.jpg + :scale: 25 % + :alt: CSE-505-203B Back + +.. figure:: /_static/images/1u_vyos_front.jpg + :scale: 25 % + :alt: CSE-505-203B Front + +.. figure:: /_static/images/1u_vyos_front_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B Open 1 + +.. figure:: /_static/images/1u_vyos_front_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B Open 2 + +.. figure:: /_static/images/1u_vyos_front_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 1 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 2 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open |