docs/troubleshooting/reportingissues/reportingissues.rst

   1 .. _reportingbugs:
   2
   3 .. toctree::
   4
   5 Reporting Bugs
   6 ==============
   7
   8 Although every situation is different, this section describes how to
   9 collect data which will help make efficient use of everyone's time
  10 when dealing with vpp bugs.
  11
  12 Before you press the Jira button to create a bug report - or email
  13 vpp-dev@lists.fd.io - please ask yourself whether there's enough
  14 information for someone else to understand and to reproduce the issue
  15 given a reasonable amount of effort. **Unicast emails to maintainers,
  16 committers, and the project PTL are strongly discouraged.**
  17
  18 A good strategy for clear-cut bugs: file a detailed Jira ticket, and
  19 then send a short description of the issue to vpp-dev@lists.fd.io,
  20 perhaps from the Jira ticket description. It's fine to send email to
  21 vpp-dev@lists.fd.io to ask a few questions **before** filing Jira tickets.
  22
  23 Data to include in bug reports
  24 ==============================
  25
  26 Image version and operating environment
  27 ---------------------------------------
  28
  29 Please make sure to include the vpp image version and command-line arguments.
  30
  31 .. code-block:: console
  32
  33     $ sudo bash
  34     # vppctl show version verbose cmdline
  35     Version:                  v18.07-rc0~509-gb9124828
  36     Compiled by:              vppuser
  37     Compile host:             vppbuild
  38     Compile date:             Fri Jul 13 09:05:37 EDT 2018
  39     Compile location:         /scratch/vpp-showversion
  40     Compiler:                 GCC 7.3.0
  41     Current PID:              5211
  42     Command line arguments:
  43       /scratch/vpp-showversion/build-root/install-vpp_debug-native/vpp/bin/vpp
  44       unix
  45       interactive
  46
  47 With respect to the operating environment: if misbehavior involving a
  48 specific VM / container / bare-metal environment is involved, please
  49 describe the environment in detail:
  50
  51 * Linux Distro (e.g. Ubuntu 18.04.2 LTS, CentOS-7, etc.)
  52 * NIC type(s) (ixgbe, i40e, enic, etc. etc.), vhost-user, tuntap
  53 * NUMA configuration if applicable
  54
  55 Please note the CPU architecture (x86_86, aarch64), and hardware platform.
  56
  57 When practicable, please report issues against released software, or
  58 unmodified master/latest software.
  59
  60 "Show" command output
  61 ---------------------
  62
  63 Every situation is different. If the issue involves a sequence of
  64 debug CLI command, please enable CLI command logging, and send the
  65 sequence involved. Note that the debug CLI is a developer's tool -
  66 **no warranty express or implied** - and that we may choose not to fix
  67 debug CLI bugs.
  68
  69 Please include "show error" [error counter] output. It's often helpful
  70 to "clear error", send a bit of traffic, then "show error"
  71 particularly when running vpp on noisy networks.
  72
  73 Please include ip4 / ip6 / mpls FIB contents ("show ip fib", "show ip6
  74 fib", "show mpls fib", "show mpls tunnel").
  75
  76 Please include "show hardware", "show interface", and "show interface
  77 address" output
  78
  79 Here is a consolidated set of commands that are generally useful
  80 before/after sending traffic.  Before sending traffic:
  81
  82 .. code-block:: console
  83
  84     vppctl clear hardware
  85     vppctl clear interface
  86     vppctl clear error
  87     vppctl clear run
  88
  89 Send some traffic and then issue the following commands.
  90
  91 .. code-block:: console
  92
  93     vppctl show version verbose
  94     vppctl show hardware
  95     vppctl show hardware address
  96     vppctl show interface
  97     vppctl show run
  98     vppctl show error
  99
 100 Here are some protocol specific show commands that may also make
 101 sense.  Only include those features which have been configured.
 102
 103 .. code-block:: console
 104
 105      vppctl show l2fib
 106      vppctl show bridge-domain
 107
 108      vppctl show ip fib
 109      vppctl show ip arp
 110
 111      vppctl show ip6 fib
 112      vppctl show ip6 neighbors
 113
 114      vppctl show mpls fib
 115      vppctl show mpls tunnel
 116
 117 Network Topology
 118 ----------------
 119
 120 Please include a crisp description of the network topology, including
 121 L2 / IP / MPLS / segment-routing addressing details. If you expect
 122 folks to reproduce and debug issues, this is a must.
 123
 124 At or above a certain level of topological complexity, it becomes
 125 problematic to reproduce the original setup.
 126
 127 Packet Tracer Output
 128 --------------------
 129
 130 If you capture packet tracer output which seems relevant, please include it.
 131
 132 .. code-block:: console
 133
 134     vppctl trace add dpdk-input 100  # or similar
 135
 136 send-traffic
 137
 138 .. code-block:: console
 139
 140     vppctl show trace
 141
 142 Capturing post-mortem data
 143 ==========================
 144
 145 It should go without saying, but anyhow: **please put post-mortem data
 146 in obvious, accessible places.** Time wasted trying to acquire
 147 accounts, credentials, and IP addresses simply delays problem
 148 resolution.
 149
 150 Please remember to add post-mortem data location information to Jira
 151 tickets.
 152
 153 Syslog Output
 154 -------------
 155
 156 The vpp signal handler typically writes a certain amount of data in
 157 /var/log/syslog before exiting. Make sure to check for evidence, e.g
 158 via "grep /usr/bin/vpp /var/log/syslog" or similar.
 159
 160 Binary API Trace
 161 ----------------
 162
 163 If the issue involves a sequence of control-plane API messages - even
 164 a very long sequence - please enable control-plane API
 165 tracing. Control-plane API post-mortem traces end up in
 166 /tmp/api_post_mortem.<pid>.
 167
 168 Please remember to put post-mortem binary api traces in accessible
 169 places.
 170
 171 These API traces are especially helpful in cases where the vpp engine
 172 is throwing traffic on the floor, e.g. for want of a default route or
 173 similar.
 174
 175 Make sure to leave the default stanza "... api-trace { on } ... " in
 176 the vpp startup configuration file /etc/vpp/startup.conf, or to
 177 include it in the command line arguments passed by orchestration
 178 software.
 179
 180 Core Files
 181 ----------
 182
 183 Production systems, as well as long-running pre-production soak-test
 184 systems, **must** arrange to collect core images. There are various
 185 ways to configure core image capture, including e.g. the Ubuntu
 186 "corekeeper" package. In a pinch, the following very basic sequence
 187 will capture usable vpp core files in /tmp/dumps.
 188
 189 .. code-block:: console
 190
 191     # mkdir -p /tmp/dumps
 192     # sysctl -w debug.exception-trace=1
 193     # sysctl -w kernel.core_pattern="/tmp/dumps/%e-%t"
 194     # ulimit -c unlimited
 195     # echo 2 > /proc/sys/fs/suid_dumpable
 196
 197 If you start VPP from systemd, you also need to edit
 198 /lib/systemd/system/vpp.service and uncomment the "LimitCORE=infinity"
 199 line before restarting VPP.
 200
 201 Vpp core files often appear enormous, but they are invariably
 202 sparse. Gzip compresses them to manageable sizes. A multi-GByte
 203 corefile often compresses to 10-20 Mbytes.
 204
 205 When decompressing a vpp core file, we suggest using "dd" as shown to
 206 create a sparse, uncompressed core file:
 207
 208 .. code-block:: console
 209
 210    $ zcat vpp_core.gz | dd conv=sparse of=vpp_core
 211
 212 Please remember to put compressed core files in accessible places.
 213
 214 Make sure to leave the default stanza "... unix { ... full-coredump
 215 ... } ... " in the vpp startup configuration file
 216 /etc/vpp/startup.conf, or to include it in the command line arguments
 217 passed by orchestration software.
 218
 219 Core files from Private Images
 220 ==============================
 221
 222 Core files from private images require special handling. If it's
 223 necessary to go that route, copy the **exact** Debian packages (or
 224 RPMs) which correspond to the core file to the same public place as
 225 the core file. A no-excuses-allowed, hard-and-fast requirement.
 226
 227 In particular:
 228
 229 .. code-block:: console
 230
 231   libvppinfra_<version>_<arch>.deb # vppinfra library
 232   libvppinfra-dev_<version>_<arch>.deb # vppinfra library development pkg
 233   vpp_<version>_<arch>.deb         # the vpp executable
 234   vpp-dbg_<version>_<arch>.deb     # debug symbols
 235   vpp-dev_<version>_<arch>.deb     # vpp development pkg
 236   vpp-lib_<version>_<arch>.deb     # shared libraries
 237   vpp-plugin-core_<version>_<arch>.deb # core plugins
 238   vpp-plugin-dpdk_<version>_<arch>.deb # dpdk plugin
 239
 240 For reference, please include git commit-ID, branch, and git repo
 241 information [for repos other than gerrit.fd.io] in the Jira ticket.
 242
 243 Note that git commit-ids are crypto sums of the head [latest]
 244 **merged** patch. They say **nothing whatsoever** about local
 245 workspace modifications, branching, or the git repo in question.
 246
 247 Even given a byte-for-byte identical source tree, it's easy to build
 248 dramatically different binary artifacts. All it takes is a different
 249 toolchain version.
 250
 251
 252 On-the-fly Core File Compression
 253 --------------------------------
 254
 255 Depending on operational requirements, it's possible to compress
 256 corefiles as they are generated. Please note that it takes several
 257 seconds' worth of wall-clock time to compress a vpp core file on the
 258 fly, during which all packet processing activities are suspended.
 259
 260 To create compressed core files on the fly, create the following
 261 script, e.g. in /usr/local/bin/compressed_corefiles, owned by root,
 262 executable:
 263
 264 .. code-block:: console
 265
 266   #!/bin/sh
 267   exec /bin/gzip -f - >"/tmp/dumps/core-$1.$2.gz"
 268
 269 Adjust the kernel core file pattern as shown:
 270
 271 .. code-block:: console
 272
 273   sysctl -w kernel.core_pattern="|/usr/local/bin/compressed_corefiles %e %t"
 274
 275 Core File Summary
 276 -----------------
 277
 278 Bottom line: please follow core file handling instructions to the
 279 letter. It's not complicated. Simply copy the exact Debian packages or
 280 RPMs which correspond to core files to accessible locations.
 281
 282 If we go through the setup process only to discover that the image and
 283 core files don't match, it will simply delay resolution of the issue;
 284 to say nothing of irritating the person who just wasted their time.