Difference between revisions of "FAQ"

From VyOS Wiki
Jump to: navigation, search
(clean up extra help text about command shorthand)
 
(20 intermediate revisions by 11 users not shown)
Line 2: Line 2:
 
== What is VyOS? ==
 
== What is VyOS? ==
  
VyOS is a routing/firewall/VPN platform , forked from Vyatta, based on Debian GNU/Linux that runs on x86 hardware and many virtual machine hypervisors.
+
VyOS is a routing/firewall/VPN platform, forked from Vyatta, based on Debian GNU/Linux that runs on x86 and ARM hardware and many virtual machine hypervisors.
  
== Should I try it? ==
+
== Who is it for? ==
  
It depends. If you are a network engineer/administrator or want to become one, you should. VyOS is more like IOS, JunOS and other enterprise platforms, not like SOHO appliances (D-Link, Linksys etc.). You need to understand what you are doing to configure it.
+
VyOS focuses on enterprise and service provider routers. It is more like Cisco IOS or Juniper JunOS, rather than SOHO routers like Linksys or D-Link.
 
+
If you are an experienced network administrator or want to learn about networking, you should try it out.
== What version should I install? ==
 
The latest one. Newer versions are always better than older.
 
 
 
== How often are new versions released? ==
 
The first official version was released on December 22nd 2013. We ask your involvement by testing our [[nightly builds]] and report any problems you experience.
 
  
 
== What functions does VyOS lack? ==
 
== What functions does VyOS lack? ==
 
There are some. For instance it lacks
 
There are some. For instance it lacks
 
* MPLS,
 
* MPLS,
* PBR (can be done with a trick),
 
 
* WebVPN,
 
* WebVPN,
 
* PPTP and L2TP clients,
 
* PPTP and L2TP clients,
Line 23: Line 17:
 
Most of the currently lacking features are to be implemented in future releases.
 
Most of the currently lacking features are to be implemented in future releases.
  
== Does VyOS support other hardware platorms (MIPS, ARM etc.) or will it support them in the future? ==
+
== Does VyOS support non-x86 hardware platforms (MIPS, ARM...) or will it support them in the future? ==
It does not. One of project goals is to make it work on widely used hardware.
+
Not at this time. We focus on support for widely available hardware.
 +
 
 +
If ARM or MIPS devices that are widely available, sufficiently powerful, and support a standardized boot process appear on the market, we'll consider supporting them.
  
 
= Installation =
 
= Installation =
 
== What hardware requirements does VyOS have? ==
 
== What hardware requirements does VyOS have? ==
  
Hardware requirements strongly depend on purpose your appliance is used for. For small branch offices Atom/C3 CPU and 256-384M RAM should be enough; for edge routers, large VPN concentrators and other high loaded appliances you should consider powerful servers.
+
Hardware requirements strongly depend on purpose your appliance is used for. For small branch offices Atom/C3 CPU and 256-384M RAM should be enough; for edge routers, large VPN concentrators, and other high load appliances you should consider powerful servers.
  
 
== How much disk space do I need? ==
 
== How much disk space do I need? ==
Line 39: Line 35:
 
Preferred way is to use image-based upgrade. Find the latest image and type command "add system image <image URL>". You may download the image to your appliance and specify path to file as the argument, or specify a remote URL.
 
Preferred way is to use image-based upgrade. Find the latest image and type command "add system image <image URL>". You may download the image to your appliance and specify path to file as the argument, or specify a remote URL.
  
Do not use 'full-upgrade -k', it may ruin your setup irrecoverable.
+
Do not try to upgrade your installation through APT unless you are intimately familiar with VyOS package base. The outcome is unpredictable and it may result in a ruined installation.
  
 
== Can I install VyOS on an embedded platform? ==
 
== Can I install VyOS on an embedded platform? ==
  
Basically yes. try it!
+
Depends on the definition of embedded. If the issue is that you cannot boot it from a CD or access its console, the recommended way is to prepare an image with require config customizations,
 +
for example in a virtual machine, then convert the VM image to raw and flash it to the boot medium of the device.
  
== Can I install on a CompactFlash? ==
+
== Can I install on CompactFlash or USB flash media? ==
 
You can, but you should reduce writing in this case (redirect logs to a remote syslog server etc.). It is better to use enterprise grade SLC cards rather than consumer grade.
 
You can, but you should reduce writing in this case (redirect logs to a remote syslog server etc.). It is better to use enterprise grade SLC cards rather than consumer grade.
  
Line 51: Line 48:
  
 
== What hypervisors can I use? ==
 
== What hypervisors can I use? ==
VMWare and XenServer are officially supported and appliance templates are provided for them. If you want to install on a Xen VM, use livecd-virt, it had Xen-aware kernel.
 
 
KVM and VirtualBox are known to work without troubles.
 
 
There are no reports about other hypervisors, but in theory they also should work.
 
 
= Usage =
 
== How do I install debian packages? ==
 
First configure repositories. The Hydrogen release will be based on Debian Squeeze so:
 
<pre>
 
set system package repository squeeze components 'main contrib non-free'
 
set system package repository squeeze distribution 'squeeze'
 
set system package repository squeeze url 'http://mirrors.kernel.org/debian'
 
</pre>
 
 
Squeeze is not supported anymore, however Helium has some packages from Squeeze Long Term Support so:
 
<pre>
 
set system package repository squeeze-lts components 'main contrib non-free'
 
set system package repository squeeze-lts distribution 'squeeze-lts'
 
set system package repository squeeze-lts url 'http://mirrors.kernel.org/debian'
 
</pre>
 
  
In case you need more modern software or software that standard isn't available in squeeze, add
+
We officially support KVM, Xen, VMware, Hyper-V, and VirtualBox.
 +
Integration levels vary: for KVM and VMware we include guest tools in addition to paravirtual drivers.
  
<pre>
+
Other x86 hypervisors should work, but we haven't tested them ourselves. If you are using them successfully, let us know.
set system package repository squeeze-backports components main
 
set system package repository squeeze-backports distribution squeeze-backports
 
set system package repository squeeze-backports url 'http://backports.debian.org/debian-backports'
 
</pre>
 
 
 
Then do "sudo apt-get update" and you can install packages with "sudo apt-get install xxxxxxx" as usual.
 
  
 
= Configuration =
 
= Configuration =
Line 89: Line 60:
 
  conf
 
  conf
  
== How do list the current config?==
+
== How do I view the current config?==
 
  show
 
  show
  
== Once in configure, can I use commands that are normally available outside config mode ?==
+
If you want to view only one subtree, you can specify the path:
 +
show interfaces ethernet eth0
 +
show interfaces
 +
show firewall
 +
 
 +
== Once in configure, can I use commands that are normally available outside config mode? ==
 
  add "run" in front of the command, eg: run show interfaces
 
  add "run" in front of the command, eg: run show interfaces
  
Line 111: Line 87:
  
 
== I added a user with "useradd"/edited a config in /etc and everything is lost after reboot! ==
 
== I added a user with "useradd"/edited a config in /etc and everything is lost after reboot! ==
Do not do this. Backend configuration files are created by vyatta code at config loading or commit. All configuration changes must be done with native CLI ("set" commands).
+
Do not do this. System configuration files are created by the VyOS config scripts on config loading or commit. All configuration changes must be done with native CLI ("set" commands).
  
 
If you do not have in depth understanding of VyOS code, it is better to forget it has Linux inside.
 
If you do not have in depth understanding of VyOS code, it is better to forget it has Linux inside.
  
== Is it possible to make vyatta show all the settings, line by line? So it is easy to use copy and paste ? ==
+
== Is it possible to show current configuration as set commands for easy copy/paste ==
run the command "show configuration commands"
+
 
 +
Yes. To view the complete running configuration as set commands, use operaional command "show configuration commands".
 +
 
 +
In configuration mode, you can also use "| commands" filter:
 +
<pre>
 +
vyos@vyos# show system | commands
 +
set config-management commit-revisions '100'
 +
comment config-management 'foo'
 +
set console device ttyS0 speed '9600'
 +
set host-name 'vyos'
 +
...
 +
</pre>
 +
 
 +
You can also use the "vyos-config-to-commands" utility to convert arbitrary VyOS config file to commands:
 +
<pre>
 +
vyos@vyos# vyos-config-to-commands /config/someconfig.conf
 +
</pre>
  
== How do I enable web GUI? ==
 
There isn't one (yet)
 
There are some initiatives like [http://www.vyatta4people.org/vybuddy-virtual-appliance-created/ vyBuddy] by [[Cartman]].
 
Might get integrated in a later version.
 
  
 
== Firewall ==
 
== Firewall ==
Line 131: Line 119:
  
 
=== I created a firewall instance, but it does not filter anything. ===
 
=== I created a firewall instance, but it does not filter anything. ===
You should apply it to an interface to make it work.
+
You should apply it to an interface to make it work. There are three directions: "in" (inbound forwarded traffic"), "local" (traffic to the router), and "out" (outbound forwarded traffic).
 +
 
 +
<pre>
 +
vyos@vyos# set interfaces ethernet eth0 firewall in name Foo
 +
</pre>
  
 
=== If I have firewall enabled, is traffic described in NAT rules automatically enabled? ===
 
=== If I have firewall enabled, is traffic described in NAT rules automatically enabled? ===
 
No, it is not. If you have both firewall and NAT, you should have both filtering rule to allow traffic and NAT rule to do translation.
 
No, it is not. If you have both firewall and NAT, you should have both filtering rule to allow traffic and NAT rule to do translation.
 +
 +
=== Can I have a zone based firewall as opposed to interface based? ===
 +
Definitely, the standard firewall rules can be supplemented into this hierarchy shown below.
 +
 +
'''Remember:''' each zone that needs to communicate must have a policy allowing it to. ie: if a DMZ zone is needed then the zone would need a firewall name and 'from' PUBLIC and another firewall name and 'from' PRIVATE.
 +
firewall names and rules are created as usual, however in more complex topologies zone based firewalls are easier to manage and scale.
 +
 +
<pre>
 +
set zone-policy zone PUBLIC from PRIVATE firewall name private_to_public
 +
set zone-policy zone PUBLIC interfaces eth0
 +
 +
set zone-policy zone PRIVATE from PUBLIC firewall name public_to_private
 +
set zone-policy zone PRIVATE interfaces eth1
 +
 +
set zone-policy zone LOCAL from PUBLIC firewall name public_to_local
 +
set zone-policy zone LOCAL local-zone
 +
</pre>
 +
 +
== How can I have system command(s) run on boot? ==
 +
In VyOS 1.2.0 or newer, to run a command on boot ''after'' config is loaded, add the command(s) to /config/scripts/vyos-postconfig-bootup.script
 +
 +
In the version 1.1.8, you should use /config/scripts/vyatta-postconfig-bootup.script file instead. The old file name is also supported by 1.2.0+
 +
  
 
= Troubleshooting =
 
= Troubleshooting =
 
== How do I view logs? ==
 
== How do I view logs? ==
  
Use operational command "monitor log" to view all log messages. You also may use "show log tail" comand to monitor latest messages in real time.
+
Use operational command "show log" to view all log messages or "show log tail" for the latest. You also may use "monitor log" command to monitor logged messages in real time.
 +
 
 +
= Development =
 +
== Which branch should I develop on ==
 +
Development efforts should be directed towards VyOS 1.2.
 +
 
 +
VyOS 1.2 development and beyond occurs on the current branch and is build using vyos-build as starting point ([https://github.com/vyos/vyos-build/blob/current/README.md| readme]).
 +
 
 +
 
 +
== I submitted a pull-request on Github ==
 +
It can happen that we lose track of your pull-request. If that's the case create a task in phabricator to call attention to it. Read more about this in [[Report a bug]].
  
 
= Other questions =
 
= Other questions =

Latest revision as of 11:43, 29 July 2018

Contents

General Questions

What is VyOS?

VyOS is a routing/firewall/VPN platform, forked from Vyatta, based on Debian GNU/Linux that runs on x86 and ARM hardware and many virtual machine hypervisors.

Who is it for?

VyOS focuses on enterprise and service provider routers. It is more like Cisco IOS or Juniper JunOS, rather than SOHO routers like Linksys or D-Link. If you are an experienced network administrator or want to learn about networking, you should try it out.

What functions does VyOS lack?

There are some. For instance it lacks

  • MPLS,
  • WebVPN,
  • PPTP and L2TP clients,
  • IPv6 flow accounting.

Most of the currently lacking features are to be implemented in future releases.

Does VyOS support non-x86 hardware platforms (MIPS, ARM...) or will it support them in the future?

Not at this time. We focus on support for widely available hardware.

If ARM or MIPS devices that are widely available, sufficiently powerful, and support a standardized boot process appear on the market, we'll consider supporting them.

Installation

What hardware requirements does VyOS have?

Hardware requirements strongly depend on purpose your appliance is used for. For small branch offices Atom/C3 CPU and 256-384M RAM should be enough; for edge routers, large VPN concentrators, and other high load appliances you should consider powerful servers.

How much disk space do I need?

At least 2 GB. More space is recomended to be able to upgrade your installation via image (see questions below).

How do I upgrade my installation?

Preferred way is to use image-based upgrade. Find the latest image and type command "add system image <image URL>". You may download the image to your appliance and specify path to file as the argument, or specify a remote URL.

Do not try to upgrade your installation through APT unless you are intimately familiar with VyOS package base. The outcome is unpredictable and it may result in a ruined installation.

Can I install VyOS on an embedded platform?

Depends on the definition of embedded. If the issue is that you cannot boot it from a CD or access its console, the recommended way is to prepare an image with require config customizations, for example in a virtual machine, then convert the VM image to raw and flash it to the boot medium of the device.

Can I install on CompactFlash or USB flash media?

You can, but you should reduce writing in this case (redirect logs to a remote syslog server etc.). It is better to use enterprise grade SLC cards rather than consumer grade.

Avoid using USB sticks in production, they are not intended for intensive usage and often fail.

What hypervisors can I use?

We officially support KVM, Xen, VMware, Hyper-V, and VirtualBox. Integration levels vary: for KVM and VMware we include guest tools in addition to paravirtual drivers.

Other x86 hypervisors should work, but we haven't tested them ourselves. If you are using them successfully, let us know.

Configuration

How do I enter configuration mode?

configure

Commands accept abbreviations wherever they are unique, so in this case you can type:

conf

How do I view the current config?

show

If you want to view only one subtree, you can specify the path:

show interfaces ethernet eth0
show interfaces
show firewall

Once in configure, can I use commands that are normally available outside config mode?

add "run" in front of the command, eg: run show interfaces

Can I see a history of commands given previously ?

history

How do I apply my changes?

commit

I am afraid my changes may break connectivity or make system inaccessible in other way. What should I do?

commit-confirm <MINUTES>

If everything is ok, issue

confirm

If you do not issue "confirm" command in given MINUTES (default is 10), your router will reboot and rollback to previous configuration.

I changed configuration and then changed my mind about commiting them. What can I do?

discard

I added a user with "useradd"/edited a config in /etc and everything is lost after reboot!

Do not do this. System configuration files are created by the VyOS config scripts on config loading or commit. All configuration changes must be done with native CLI ("set" commands).

If you do not have in depth understanding of VyOS code, it is better to forget it has Linux inside.

Is it possible to show current configuration as set commands for easy copy/paste

Yes. To view the complete running configuration as set commands, use operaional command "show configuration commands".

In configuration mode, you can also use "| commands" filter:

vyos@vyos# show system | commands
set config-management commit-revisions '100'
comment config-management 'foo'
set console device ttyS0 speed '9600'
set host-name 'vyos'
...

You can also use the "vyos-config-to-commands" utility to convert arbitrary VyOS config file to commands:

vyos@vyos# vyos-config-to-commands /config/someconfig.conf


Firewall

Is any traffic filtering enabled by default?

No.

Is there a way to filter traffic originated by router itself?

Per-interface firewall for local only control inbound connectivity. If you use zone-policy firewall, you can restrict in or outbound traffic from the router.

I created a firewall instance, but it does not filter anything.

You should apply it to an interface to make it work. There are three directions: "in" (inbound forwarded traffic"), "local" (traffic to the router), and "out" (outbound forwarded traffic).

vyos@vyos# set interfaces ethernet eth0 firewall in name Foo

If I have firewall enabled, is traffic described in NAT rules automatically enabled?

No, it is not. If you have both firewall and NAT, you should have both filtering rule to allow traffic and NAT rule to do translation.

Can I have a zone based firewall as opposed to interface based?

Definitely, the standard firewall rules can be supplemented into this hierarchy shown below.

Remember: each zone that needs to communicate must have a policy allowing it to. ie: if a DMZ zone is needed then the zone would need a firewall name and 'from' PUBLIC and another firewall name and 'from' PRIVATE. firewall names and rules are created as usual, however in more complex topologies zone based firewalls are easier to manage and scale.

set zone-policy zone PUBLIC from PRIVATE firewall name private_to_public
set zone-policy zone PUBLIC interfaces eth0

set zone-policy zone PRIVATE from PUBLIC firewall name public_to_private
set zone-policy zone PRIVATE interfaces eth1

set zone-policy zone LOCAL from PUBLIC firewall name public_to_local
set zone-policy zone LOCAL local-zone

How can I have system command(s) run on boot?

In VyOS 1.2.0 or newer, to run a command on boot after config is loaded, add the command(s) to /config/scripts/vyos-postconfig-bootup.script

In the version 1.1.8, you should use /config/scripts/vyatta-postconfig-bootup.script file instead. The old file name is also supported by 1.2.0+


Troubleshooting

How do I view logs?

Use operational command "show log" to view all log messages or "show log tail" for the latest. You also may use "monitor log" command to monitor logged messages in real time.

Development

Which branch should I develop on

Development efforts should be directed towards VyOS 1.2.

VyOS 1.2 development and beyond occurs on the current branch and is build using vyos-build as starting point (readme).


I submitted a pull-request on Github

It can happen that we lose track of your pull-request. If that's the case create a task in phabricator to call attention to it. Read more about this in Report a bug.

Other questions

How do I shot web?

We dunno, lol.