This knowledge base has moved to the documentation site. Please visit the knowledge base here for the most up to date content. This site is no longer maintained.

[RETIRED] Troubleshooting Linux Server Interfaces Using netshow


IMPORTANT! This article has been retired. The netshow documentation is now available in the Cumulus Linux user guide.



Some History

Linux devices originally only supported very few interfaces, say two to five for example. Today, it is becoming more common to find Linux devices with 50 or more interfaces. Two examples of these are switches running Cumulus Linux and OpenStack Linux hypervisors.


What Is netshow?

netshow is a tool designed by network operators for network troubleshooters. Existing command line tools have too many options! netshow addresses this by leveraging the network troubleshooting experience from a wide group of troubleshooters and boiling it down to just a few important options. netshow quickly aggregates basic network information on Linux devices with numerous interfaces. netshow intelligently informs the administrator what network type an interface belongs to, and shows the most relevant information to a network administrator.

A simple netshow --help should tell you all you need to know about it.

netshow -h

    netshow system [--json | -j ]
    netshow lldp [--json | -j | -l | --legend]
    netshow interface [<iface>] [all] [--mac | -m ] [--oneline | -1 | --json | -j | -l | --legend ]
    netshow access [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow bridges [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow bonds [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow bondmems [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow l2 [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow l3 [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow trunks [all] [--mac | -m ] [--oneline | -1  | --json | -j | -l | --legend ]
    netshow (--version | -V)

    * default is to show intefaces only in the UP state.
    interface                 summary info of all interfaces
    access                    summary of physical ports with l2 or l3 config
    bonds                     summary of bonds
    bondmems                  summary of bond members
    bridges                   summary of ports with bridge members
    l3                        summary of ports with an IP.
    l2                        summary of access, trunk and bridge interfaces
    trunks                    summary of trunk interfaces
    lldp                      physical device neighbor information
    interface <iface>         list summary of a single interface
    system                    system information

    all        show all ports include those are down or admin down
    --mac      show inteface MAC in output
    --version  netshow software version
    --oneline  output each entry on one line
    -1         alias for --oneline
    --json     print output in json
    -l         alias for --legend
    --legend   print legend key explaining abbreviations

A Linux administrator can quickly see the few options available with the tool. One core tenet of netshow is for it to have a small number of command options. netshow is not designed to solve your network problem, but to help answer this simple question: "What is the basic network setup of my Linux device?" By helping to answer that question, a Linux administrator can spend more time troubleshooting the specific network problem instead of spending most of their time understanding the basic network state.

Originally developed for Cumulus Linux, netshow works on Debian-based servers and switches and Red Hat-based Linux systems. 

netshow is designed by network operators, which has rarely occurred in the networking industry, where most command troubleshooting tools are designed by developers and are most useful in the network application development process.

netshow is still in beta development, but shows lots of promise of simplifying the basic network troubleshooting workflow of Linux administrators.


Installing netshow in Cumulus Linux

To install netshow in Cumulus Linux, please read this knowledge base article.

Installing netshow on a Linux Server or in OpenStack

To install netshow on a Linux server, run:

pip install netshow-linux-lib

Note: Debian and Red Hat packages will be available in the near future.

Troubleshooting Example: OpenStack

Looking at an OpenStack Environment, here is the physical diagram:

For server2, netshow can help us see the OpenStack network configuration. The netshow output below shows an summary of a Kilo-based OpenStack server running 3 tenants.

[root@server2 ~]# netshow int
To view the legend,  rerun "netshow" cmd with the  "--legend" option
    Name            Speed    MTU    Mode            Summary
--  --------------  -------  -----  --------------  ---------------------------------------------------------------------
UP  brq0b6f10c7-42  N/A      1500   Bridge/L2       802.1q Tag: 141
                                                    STP: Disabled
                                                    Untagged Members: tap079cf993-c7
                                                    Tagged Members: eth1.141
UP  brq8cdc0589-9b  N/A      1500   Bridge/L2       802.1q Tag: 155
                                                    STP: Disabled
                                                    Untagged Members: tap5353b20a-68
                                                    Tagged Members: eth1.155
UP  brq8ff99102-29  N/A      1500   Bridge/L2       802.1q Tag: 168
                                                    STP: Disabled
                                                    Untagged Members: tapfc2203e4-5b
                                                    Tagged Members: eth1.168
UP  eth0            N/A      1500   Interface/L3    IP:
UP  eth1            N/A      1500   IntTypeUnknown
UP  eth1            N/A      1500   Trunk/L2        Bridge Membership:
                                                    Tagged: brq0b6f10c7-42(141), brq8cdc0589-9b(155), brq8ff99102-29(168)
UP  lo              N/A      65536  Loopback        IP:, ::1/128
UP  tap079cf993-c7  10M      1500   Access/L2       Untagged: brq0b6f10c7-42
UP  tap5353b20a-68  10M      1500   Access/L2       Untagged: brq8cdc0589-9b
UP  tapfc2203e4-5b  10M      1500   Access/L2       Untagged: brq8ff99102-29

OpenStack interface numbering is not the easiest read, but here netshow can quickly show you:

  • A list of all the interfaces in admin UP state and carrier UP state
  • 3 bridges
  • That STP is disabled for all the bridges
  • An uplink trunk interface with 3 VLANs configured on it
  • Many tap interfaces, most likely the virtual machines

This output took about 5 seconds to get and another 1 minute to analyze. To get this same level of understanding using traditional tools such as:

  • ip link show
  • brctl show
  • ip addr show

... could take about 10 minutes. This is a significant improvement in productivity!

netshow uses a plugin architecture and can be easily expanded. An OpenStack interface discovery module is currently in development. If netshow is run on a hypervisor with OpenStack Keystone login environment variables like OS_TENANT_NAME, netshow should show the above output with a better interface discovery state, where netshow collects from OpenStack information from libvirt, nova and neutron to overlay the virtual machine and tenant subnet information over the interface kernel state information.

Interface discovery is one of the most powerful features of netshow. The ability to expand its interface discovery capabilities further simplifies understanding basic network troubleshooting, making the Linux administrator more productive and improving time to resolution while investigating network problems.

Other Useful netshow Features

netshow uses the python network-docopt package. This is inspired by docopt and provides the ability to specify partial commands, without tab completion and running the complete option. For example:

netshow int runs netshow interface
netshow sys runs netshow system

netshow will eventually support interface name autocompletion. In the near future, if you run netshow int tap123 and there is only one interface starting with tap123, netshow will autocomplete the command option with the full interface.

Contributions Welcome!

netshow is an open source project licensed under GPLv2. To contribute please contact Cumulus Networks through the Cumulus Community Forum or the Netshow Linux Provider Github Repository Home. You can find developer documentation at The documentation is still under development.


This support portal has moved

Cumulus Networks is now part of the NVIDIA Networking Business Unit! The NVIDIA Cumulus Global Support Services (GSS) team has merged its operations with the NVIDIA Mellanox support services team.

You can access NVIDIA Cumulus support content from the Mellanox support portal.

You open and update new cases on the Mellanox support portal. Any previous cases that have been closed have been migrated to the Mellanox support portal.

Cases that are still open on the Cumulus portal will continue to be managed on the Cumulus portal. Once these cases close, they will be moved to the Mellanox support portal.

Powered by Zendesk