UniFi - Methods for Capturing Useful Debug Information


Overview


In this article, the reader will learn methods to capture useful debug information when troubleshooting with UBNT Support in the Community. Please start a thread in the Community, or comment on an existing one, and remember to tag a UniFi representative: UBNT-MikeD, UBNT-BenBuckley, UBNT-jeff, or UBNT-DavidS to name a few.


Table of Contents


  1. Introduction
  2. How to Configure Remote Logging
  3. How to Share Remote Logging Information
  4. Capturing Traffic with tcpdump
  5. Tech Support File
  6. Related Articles

Introduction


Back to Top

One of the first things UBNT Support will ask for when debugging is the output of cat /var/log/messages or dmesg. In some cases, however, messages can't be sent back over an SSH session to the user. Another common scenario is that the user is not actually logged in when the issue happens, so they are unable to see the output and the messages are lost when the AP reboots. The easiest solution at that point is to use a remote log server.

In addition to capturing information that resulted in a reboot, using a remote server can simplify the process of sharing log files.


How to Configure Remote Logging


Back to Top

This feature is available for UniFi Access Point (UAP) firmware versions 3.7.18 and later; please upgrade if using an older version. If it is still not available, please make sure that the UniFi Controller software is also up to date. In the UniFi Controller, navigate to Settings > Site to enable Netconsole on UAPs and UniFi Switches (USWs). This feature is not currently available for UniFi Security Gateways (USGs).


How to Share Remote Logging Information


Back to Top

After enabling netconsole, these logs will be available to UniFi developers. In order for them to identify the correct ones, you will have to let them know by doing the following:

  1. Contact the UBNT representative you have been troubleshooting with via the Community.
  2. Let him know that Remote Logging has been enabled on your UniFi Controller.
  3. Share the public-facing IP address that the log messages will be coming from: this is how the log file is identified on the UBNT server.
NOTE: The netconsole server IP for Ubiquiti is 192.76.255.30.

Capturing Traffic with tcpdump


Back to Top

Wireshark captures of what is happening in the air are extremely helpful, but sometimes it's necessary to see what the traffic looks like after having been processed by the radio. This section describes a few methods for doing just that.

Before you begin, please take a look at tcpdump manual: (external link) for more information on how to use tcpdump effectively. To use tcpdump begin by accessing the command line interface (CLI), you can do so by using a program such as PuTTY.

UniFi Access Points (UAP)

tcpdump -i <iface i.e. br0 or athX> -w /tmp/<descriptivefilename.pcapng>

Traffic can be captured on any interface of the UAP, and this command can run for as many interfaces as needed. The athX in the command above corresponds to an SSID being broadcast by the UAP. That information can be found by SSHing into the UAP and executing the iwconfig command.

This method has the notable drawback that the file is being saved on the AP, which will eventually exhaust the memory if left running for too long. It also requires that the file be retrieved when the user is done. This command can be modified to save the file to the computer from which the SSH session is running. To do so, use the following commands:

ssh <user>@<ip of AP> 'tcpdump -i <iface> src not <ip of computer> and dst not <ip of computer> -w -' > <descriptivefilename.pcapng>

The src not and dst not conditions are important because they prevent the file from being saturated with SSH traffic between the computer and the AP.

UniFi Switch (USW)

While tcpdump is available for use on the USW, only broadcast/multicast traffic or unicast to the management IP of the switch will be captured. The best method for capturing traffic from a switch is to use port mirroring in conjunction with Wireshark on a connected PC.

UniFi Security Gateway (USG)

As with the UniFi Access Points, the USG is able to capture traffic from any interface using tcpdump. See the following scenarios and the corresponding commands:

· Capturing LAN Traffic. Use eth1 for the USG model and eth0 for USG Pro.

sudo tcpdump -npi eth#

· Capturing WAN Traffic. Use eth0 for the USG model and eth2 for USG Pro.

sudo tcpdump -npi eth#

· Capturing VPN traffic (VTI-based). On VTI-based VPNs, each tunnel will be assigned a VTI. The tunnel must be up for this command to output properly.

1. To see which route is assigned to an interface, use the show command:

show ip route | grep vti

2. Once you have the VTI number for the tunnel you want to capture traffic on, use the following command, replacing the # with the VTI number:

sudo tcpdump -npi vti#

NOTE: Capturing traffic for policy-based VPN's will only show packets that are already encrypted. To get insight on traffic destined for a VPN remote network, capture on the LAN interface using a host filter on the tcpdump command.  

Tech Support File


Back to Top

CLI: To be able to output the tech support file on both the USG and the USW an SSH client such as putty is needed.

UniFi Security Gateway (USG)

1. SSH to the USG.

2. Input the following command:

show tech-support | no-more

3. Copy the full output and paste it into a text editor.

4. Save and name the file while using the .txt extension.

UniFi Switch (USW)

1. SSH to the USW. 

2. Input the following commands:

telnet localhost
enable
show tech-support

3. Press the space bar until the output is complete or until the following no longer appears:

--More-- or (q)uit

4. Copy the full output and paste it into a text editor.

5. Save and name the file while using the .txt extension.


Related Articles


Back to Top

Intro to Networking - How to Establish a Connection Using SSH


We're sorry to hear that!