Report a bug
Issues, or, in IT jargon, "bugs" are found in any software project. VyOS is not an exception.
All issues should be reported to the developers. This lets the developers know what is not working properly. Without this sort of feedback every developer will believe that everything is working correctly.
- 1 I have found a bug, what should I do?
- 2 It is a bug and I want to report it
- 3 Enhancement requests
- 4 Bug example
I have found a bug, what should I do?
Verify that it is a bug.
When you believe you have found a bug, it is always a good idea to verify the issue prior to opening a bug request.
- Consult the documentation to ensure that you have configured your system correctly.
- Get community support from user groups.
- Ask questions on the IRC.
Ensure that the problem is reproducible
When you are able to verify that it is actually a bug, spend some time to document how to reproduce the issue. This documentation can be invaluable. When you wish to have a developer fix a bug that you found, helping them reproduce the issue benefits everyone. Be sure to include information about the hardware you are using, commands that you were running, any other activities that you may have been doing at the time. This additional information can be very useful.
- What were you attempting to achieve?
- What was the configuration prior to the change?
- What commands did you use?
The output you get when you find a bug can provide lots of information. If you get an error message on the screen, copy it exactly. Having the exact message can provide detail that the developers can use. Like wise if you have any log messages that also are from the time of the issue, include those. They may also contain information that is helpful for the development team.
One handy command is the "show tech-support". This will provide detailed information that can be used while troubleshooting. One way to do this is to save it directly to an FTP or SCP server that you have. You can use the following format to export the "show tech-support" file.
show tech-support save ftp://user:password@host/path/to/file
Note: "show tech-support" includes complete configuration, so it's likely to have a lot of sensitive information, so be very careful when uploading it somewhere, especially to public resources, including the bugzilla.
If your issue is with a specific command such as OSPF, use the output of that command instead. This provides a smaller set of information for the developers to review.
If you suspect some feature is not handling traffic correctly (e.g. dropping sessions it should not or corrupting packets), attach a traffic dump. You can do this right on your router by using operational command like
show interfaces ethernet eth0 capture
It is a bug and I want to report it
Create an account on the VyOS Phabricator. VyOS Phabricator is at phabricator.vyos.net.
Then log in and use the + symbol in the upper right corner to create a new question if you are not 100% certain of your case. If you are certain (and/or can provide detailed data) create a new task. Regardless of your choice this is purely administrative to minimize work. You will get a report form you should fill in.
Elements that are not described should be considered optional. Please leave these empty unless otherwise mandated.
Write a title
Make it short and clear. Like "IPv6 interface route can not be deleted when configured". A best practice is to include the name of the feature where you found an issue. Avoid phrases like "not working" (unless the feature is really not working at all which is not seen in stable releases).
Unless you figured it out yourself leave it to Open, otherwise use Resolved if you have a patch. You can also use this to call attention to an overseen pull-request on GitHub.
You can specifically assign the bug to a certain member but it's common courtesy to leave this empty or use it for self-assignment (unless prior communication with said member).
Do not overestimate it. Priority should be interpreted as severity. The difference would be priority applies to you and your situation while severity is from the project's viewpoint. Try to evaluate how large or many users would be impacted by your bug. For example, major bugs that appear in a rare use case are likely to be fixed after minor bugs that affect everyone.
General guideline for choosing severity is the following:
- Low: Does not break any functionality. E.g. wrong sorting of rule numbers, typos or other mistakes in messages the system produces.
- Medium: Causes minor functionality loss, or has easy workaround.
- High: Causes major functionality loss, workaround is difficult.
- Unbreak Now!: Breaks feature functioning entirely or security issues.
Leave it "Needs triage" if in doubt, someone of the developers will set it. Do not think bugs with higher severity set by user are viewed or fixed first.
Write a description
Description is a place for detailed information; describe, in as much detail as possible, the bug and how to reproduce it. As the name and description may not be always enough to reproduce the bug, include the expected and actual results in the bug description. Enumerate the steps you took before you encountered the bug. Include in the description what results you expected and what you actually get. Be as specific as possible. Add a source URL where you found a bug if applicable.
Include files for proof
Visual elements, like a screenshot or a short video, will help others understand the issue better and resolve it faster. You can drag and drop images and other documents in the Description text editor. Traffic dumps, configuration files, and test cases should also be added this way.
You can search for relevant tags and add them to your task.
Notify your friends you are in distress and need their assistance. Leave empty if no friends ;)
Gauge difficulty level
Leave this empty unless you have a good insight in what needs to be done where and how.
Mention the version
The specific VyOS version you are experiencing this bug on. Use show version on your machine to get the release information.
Requests for enhancements or new features are filed similar to bugs, but with severity set to "Wishlist". Write your feature suggestion and propose CLI syntax.
Mock example of a bug developers will like.
Components: Foo Severity: Major Description: Foo fails to commit when service-type is set to "bar" Comment: #set service foo rule service-type "bar" #commit Fatal: can't use "bar". Service-type options "quux" and "baz" do not cause errors.