Reporting bugs & suggesting enhancements

This trac allows you to create new tickets, to notify the developers of bugs and to request new features. For the developers, these tickets are a way to keep track of what needs to be fixed or added, to request more information from a bug reporter and keep track in what version things have been fixed or added.

To increase the quality of the reported tickets, this page contains some guidelines and documentation. If the reported tickets are more complete, the developers can spend less time asking for more information, guessing as to what you really mean and spend more time on actually fixing bugs and adding features.

Here are some points to consider.

• Leave your email address in the reporter field. If we can't reproduce the problem and we can't contact you, we can't fix the bug! As an added bonus, you'll get notified whenever the ticket changes status.
• Use a concise, but complete summary. "Fonera problem" is a useless summary, "Music plugin problem" is not quite good, "Occasional reboots when using the music plugin for a few hours" is a good summary.
• Clearly describe the bug you found. Important questions are: "What were you doing when the bug occured?", "Can you reproduce the bug reliabley, and if so, what is the exact sequence of steps to take to trigger the bug?", "What hardware and what software version are you using?", "Is there a configuration value that can make the bug appear or go away?".
• Provide as much relevant (!) details as possible. Are there configuration details that seem relevant to you? Does the output of the "logread" command contain related info?
• For enhancement requests: How would you like the new feature to work exactly? Why would it be useful? Provide links to the relevant website if you want a new piece of software on the Fonera.

Providing information

When you report a bug, you should provide information relevant to the bug and hand. Afterwards, it's likely that a developer will ask you to provide more information. This sections provides hints on how to collect the needed information.

Developer firmware

To be able to provide more details about your problem (such as configuration or log files), you might need to install a developer firmware on your device. The developer firmwares allow access through the 'SSH' protocol, which allows you to execute commands and access files on your device.

Installing a developer firmware is the same as a normal firmware upgrade. You download the latest firmware from  http://download.fonosfera.org/LATEST/ (as a .tgz file), but be sure to pick the version with DEV in the filename. You can upload this file in the Fonera dashboard (under Settings -> System) to get the development firmware. See  http://wiki.fon.com/wiki/Firmware_Update for details.

SSH access and running commands

When you have a developer firmware, you can access your Fonera using SSH. A common SSH client for Windows machines is  PuTTY. You can use it to connect using the hostname "fonera" (or the IP address of your fonera), username "root" and the password you configured on the Fonera dashboard.

When you successfully connect using SSH, you will get a banner stating which version of the firmware you are running, followed by the command prompt. The prompt looks like this:

root@Fonera:~# 

At this command prompt, you can type commands, which will then be executed by your Fonera. The Fonera supports most of the common Linux commands.

If you're asked to execute a command, just type it at the prompt (or you can paste from the clipboard by rightclicking in PuTTY).

Getting the output of a command

When you run a command through PuTTY, the output of the command will be displayed directly underneath the command you typed (note that some commands have no output, so you'll get a new commandprompt right away). For example, the uptime command will show you what time it is, how long the Fonera has been powered on and how busy it has been recently:

root@Fonera:~# uptime
 18:14:25 up 11:11, load average: 0.02, 0.05, 0.15
root@Fonera:~#

To get the output of a command you've executed using PuTTY, you can simply select the relevant part in the PuTTY window. It will be copied to the clipboard automatically, there's no need to press CTRL-C (in fact, pressing CTRL-C in PuTTY cancels a running command!).

If a command has so much output that PuTTY's buffer is too small, you can either increase the buffer size in the settings, or redirect the output to a file. Redirecting is done by putting a > and a filename after the command. For example:

root@Fonera:~# uptime > /tmp/output.txt
root@Fonera:~#

The output of the uptime command is now stored in the file called /tmp/output.txt. To get at this file, you can use SCP (see below).

Getting the contents of a file

To get the contents of a file, you can either use the cat command through SSH (for small files) or use SCP.

The cat command simply displays a file. You put the filename to display after the command itself. For example:

root@Fonera:~# cat /tmp/output.txt
 18:14:25 up 11:11, load average: 0.02, 0.05, 0.15
root@Fonera:~#

Alternatively, you can use the SCP (Secure CoPy) protocol to access files. On Windows, the  WinSCP program allows SCP access. Login details are the same as for SSH: Use "fonera" or the ip address of your fonera for host, "root" as username and the dashboard password as password. Be sure to select the "SCP" connection type, as opposed to "SFTP" (which the Fonera does not support).

Pasting file contents or command outputs

When you're asked to provide the output of a command or the contents of a file, you should make sure to present it in a readable way.

When putting output or file contents in a trac comment, you can put it in your comment directly. However, be sure to use the Pre-formatted text wiki markup, to prevent trac from putting all of the output on a single line. For example, if I was to post a comment with the output of the above uptime command, I would type the following in the comment text field:

 I've ran the uptime command, as you asked. Here is the output:
 {{{
  18:14:25 up 11:11, load average: 0.02, 0.05, 0.15
 }}}

When the output or file is very big, you can also attach a file to a ticket. For this, use the "Attach file" button directly above the comment field.

When on IRC, you can use a  pastebin, such as on  http://pastebin.com/. Simply paste the file or output into the box, optionally set some options and press submit. You'll get a short URL that you can paste on IRC instead of spamming the channel with a lot of ouput. The general rule is that everything longer than 2 or 3 lines should end up in a pastebin instead of pasting directly.

Please do not use a pastebin when commenting on a ticket, since pastebins expire after a fairly short amount of time (and we might be working on your ticket for a while).

Uploading files to your Fonera

You might be asked to test a fix or upload a file to your Fonera. To do this, you'll need a developer firmware with SSH enabled.

You can then use the SCP (Secure CoPy) protocol to access files. On Windows, the  WinSCP program allows SCP access. Login details are the same as for SSH: Use "fonera" or the ip address of your fonera for host, "root" as username and the dashboard password as password. Be sure to select the "SCP" connection type, as opposed to "SFTP" (which the Fonera does not support).

Using WinSCP you can browse the filesystem. You will probably end up in "/tmp", so you'll need to go up one directory level to get into "/" and from there navigate to the place where you want to put the file.

Alternatively, you can use the wget command to download files onto your Fonera directly (only works if it has an internet connection, of course). For example, to get the attachment "foo.sh" from ticket number 1234 and save it into "/sbin", you run the following command on your Fonera (using SSH / PuTTY):

root@Fonera:~# wget -O /sbin/foo.sh http://trac.fonosfera.org/fon-ng/raw-attachment/ticket/1234/foo.sh