contrib/ofed/management/infiniband-diags/README

   1 Diagnostic Tools
   2 shaharf@voltaire.com, halr@voltaire.com
   3
   4 General:
   5
   6 Model of operation: All utilities use direct MAD access to perform their
   7 operations. Operations that require QP 0 mads only, may use direct routed
   8 mads, and therefore may work even in unconfigured subnets. Almost all
   9 utilities can operate without accessing the SM, unless GUID to lid translation
  10 is required.
  11
  12 Dependencies: Most utilities depend on libibmad and libibumad.
  13         All utilities depend on the ib_umad kernel module.
  14
  15 Multiple port/Multiple CA support: when no IB device or port is specified
  16         (see the "local umad parameters" below), the libibumad library
  17         selects the port to use by the following criteria:
  18         1. the first port that is ACTIVE.
  19         2. if not found, the first port that is UP (physical link up).
  20
  21         If a port and/or CA name is specified, the libibumad library
  22         attempts to fulfill the user request, and will fail if it is not
  23         possible.
  24         For example:
  25         ibaddr                  # use the 'best port'
  26         ibaddr -C mthca1        # pick the best port from mthca1 only.
  27         ibaddr -P 2             # use the second (active/up) port from the
  28                                   first available IB device.
  29         ibaddr -C mthca0 -P 2   # use the specified port only.
  30
  31 Common options & flags:
  32         Most diagnostics take the following flags. The exact list of supported
  33         flags per utility can be found in the usage message and can be shown
  34         using util_name -h syntax.
  35
  36         # Debugging flags
  37         -d      raise the IB debugging level. May be used
  38                 several times (-ddd or -d -d -d).
  39         -e      show umad send receive errors (timeouts and others)
  40         -h      show the usage message
  41         -v      increase the application verbosity level.
  42                 May be used several times (-vv or -v -v -v)
  43         -V      show the internal version info.
  44
  45         # Addressing flags
  46         -D      use directed path address arguments. The path
  47                 is a comma separated list of out ports.
  48                 Examples:
  49                 "0"             # self port
  50                 "0,1,2,1,4"     # out via port 1, then 2, ...
  51         -G      use GUID address arguments. In most cases, it is the Port GUID.
  52                 Examples:
  53                 "0x08f1040023"
  54         -s <smlid>      use 'smlid' as the target lid for SA queries.
  55
  56         # Local umad parameters:
  57         -C <ca_name>    use the specified ca_name.
  58         -P <ca_port>    use the specified ca_port.
  59         -t <timeout_ms> override the default timeout for the solicited mads.
  60
  61 CLI notation: all utilities use the POSIX style notation,
  62         meaning that all options (flags) must precede all arguments
  63         (parameters).
  64
  65
  66 Utilities descriptions:
  67
  68 1. ibstatus
  69
  70 Description:
  71 ibstatus is a script which displays basic information obtained from the local
  72 IB driver. Output includes LID, SMLID, port state, link width active, and port
  73 physical state.
  74
  75 Syntax:
  76 ibstatus [-h] [devname[:port]]...
  77
  78 Examples:
  79         ibstatus                # display status of all IB ports
  80         ibstatus mthca1         # status of mthca1 ports
  81         ibstatus mthca1:1 mthca0:2      # show status of specified ports
  82
  83 See also:
  84         ibstat
  85
  86 2. ibstat
  87
  88 Description:
  89 Similar to the ibstatus utility but implemented as a binary and not a script.
  90 It has options to list CAs and/or ports.
  91
  92 Syntax:
  93 ibstat [-d(ebug) -l(ist_of_cas) -p(ort_list) -s(hort)] <ca_name> [portnum]
  94
  95 Examples:
  96         ibstat                  # display status of all IB ports
  97         ibstat mthca1           # status of mthca1 ports
  98         ibstat mthca1 2         # show status of specified ports
  99         ibstat -p mthca0        # list the port guids of mthca0
 100         ibstat -l               # list all CA names
 101
 102 See also:
 103         ibstatus
 104
 105 3. ibroute
 106
 107 Description:
 108 ibroute uses SMPs to display the forwarding tables (unicast
 109 (LinearForwardingTable or LFT) or multicast (MulticastForwardingTable or MFT))
 110 for the specified switch LID and the optional lid (mlid) range.
 111 The default range is all valid entries in the range 1...FDBTop.
 112
 113 Syntax:
 114 ibroute [options] <switch_addr> [<startlid> [<endlid>]]]
 115
 116 Non standard flags:
 117         -a      show all lids in range, even invalid entries.
 118         -n      do not try to resolve destinations.
 119         -M      show multicast forwarding tables. In this case the range
 120                 parameters are specifying mlid range.
 121
 122 Examples:
 123         ibroute 2               # dump all valid entries of switch lid 2
 124         ibroute 2 15            # dump entries in the range 15...FDBTop.
 125         ibroute -a 2 10 20      # dump all entries in the range 10..20
 126         ibroute -n 2            # simple format
 127         ibroute -M 2            # show multicast tables
 128
 129 See also:
 130         ibtracert
 131
 132 4. ibtracert
 133
 134 Description:
 135 ibtracert uses SMPs to trace the path from a source GID/LID to a
 136 destination GID/LID. Each hop along the path is displayed until the destination
 137 is reached or a hop does not respond. By using the -m option, multicast path
 138 tracing can be performed between source and destination nodes.
 139
 140 Syntax:
 141 ibtracert [options] <src-addr> <dest-addr>
 142
 143 Non standard flags:
 144         -n              simple format; don't show additional information.
 145         -m <mlid>       show the multicast trace of the specified mlid.
 146
 147 Examples:
 148         ibtracert 2 23          # show trace between lid 2 and 23
 149         ibtracert -m 0xc000 3 5 # show multicast trace between lid 3 and 5
 150                                    for mcast lid 0xc000.
 151
 152 5. smpquery
 153
 154 Description:
 155 smpquery allows a basic subset of standard SMP queries including the following:
 156 node info, node description, switch info, port info. Fields are displayed in
 157 human readable format.
 158
 159 Syntax:
 160 smpquery [options] <op> <dest_addr> [op_params]
 161
 162 Current supported operations and their parameters:
 163         nodeinfo <addr>
 164         nodedesc <addr>
 165         portinfo <addr> [<portnum>]     # default port is zero
 166         switchinfo <addr>
 167         pkeys <addr> [<portnum>]
 168         sl2vl <addr> [<portnum>]
 169         vlarb <addr> [<portnum>]
 170
 171 Examples:
 172         smpquery nodeinfo 2             # show nodeinfo for lid 2
 173         smpquery portinfo 2 5           # show portinfo for lid 2 port 5
 174
 175 6. smpdump
 176
 177 Description:
 178 smpdump is a general purpose SMP utility which gets SM attributes from a
 179 specified SMA. The result is dumped in hex by default.
 180
 181 Syntax:
 182 smpdump [options] <dest_addr> <attr> [mod]
 183
 184 Non standard flags:
 185         -s      show output as string
 186
 187 Examples:
 188         smpdump -D 0,1,2 0x15 2         # port info, port 2
 189         smpdump 3 0x15 2                # port info, lid 3 port 2
 190
 191 7. ibaddr
 192
 193 Description:
 194 ibaddr can be used to show the lid and GID addresses of the specified port,
 195 or the local port by default.
 196 Note: this utility can be used as simple address resolver.
 197
 198 Syntax:
 199 ibaddr [options] [<dest_addr>]
 200
 201 Examples:
 202         ibaddr                  # show local address
 203         ibaddr 2                # show address of the specified port lid
 204         ibaddr -G 0x8f1040023   # show address of the specified port guid
 205
 206 8. sminfo
 207
 208 Description:
 209 sminfo issue and dumps the output of a sminfo query in human readable format.
 210 The target SM is the one listed in the local port info, or the SM specified
 211 by the optional SM lid or by the SM direct routed path.
 212 Note: using sminfo for any purposes other then simple query may be very
 213 dangerous, and may result in a malfunction of the target SM.
 214
 215 Syntax:
 216 sminfo [options] <sm_lid|sm_dr_path> [sminfo_modifier]
 217
 218 Non standard flags:
 219         -s <state>      # use the specified state in sminfo mad
 220         -p <priority>   # use the specified priority in sminfo mad
 221         -a <activity>   # use the specified activity in sminfo mad
 222
 223 Examples:
 224         sminfo                  # show sminfo of SM listed in local portinfo
 225         sminfo 2                # query SM on port lid 2
 226
 227 9. perfquery
 228
 229 Description:
 230 perfquery uses PerfMgt GMPs to obtain the PortCounters (basic performance
 231 and error counters) from the PMA at the node specified. Optionally reset all
 232 or
 233
 234 Syntax:
 235 perfquery [options]  [<lid|guid> [[port] [reset_mask]]]
 236
 237 Non standard flags:
 238         -a      show aggregated counters for all ports of the destination lid.
 239         -r      reset counters after read.
 240         -R      only reset counters.
 241
 242 Examples:
 243         perfquery               # read local port's performance counters
 244         perfquery 32 1          # read performance counters from lid 32, port 1
 245         perfquery -a 32         # read node aggregated performance counters
 246         perfquery -r 32 1       # read performance counters and reset
 247         perfquery -R 32 1       # reset performance counters of port 1 only
 248         perfquery -R -a 32      # reset performance counters of all ports
 249         perfquery -R 32 2 0xf000  # reset only non-error counters of port 2
 250
 251 10. ibping
 252
 253 Description:
 254 ibping uses vendor mads to validate connectivity between IB nodes.
 255 On exit, (IP) ping like output is show. ibping is run as client/server.
 256 Default is to run as client. Note also that a default ping server is
 257 implemented within the kernel.
 258
 259 Syntax:
 260 ibping [options] <dest lid|guid>
 261
 262 Non standard flags:
 263         -c <count>      stop after count packets
 264         -f              flood destination: send packets back to back w/o delay
 265         -o <oui>        use specified OUI number to multiplex vendor mads
 266         -S              start in server mode (do not return)
 267
 268 11. ibnetdiscover
 269
 270 Description:
 271 ibnetdiscover performs IB subnet discovery and outputs a human readable
 272 topology file. GUIDs, node types, and port numbers are displayed
 273 as well as port LIDs and NodeDescriptions. All nodes (and links) are displayed
 274 (full topology). Optionally this utility can be used to list the current
 275 connected nodes. The output is printed to the standard output unless a
 276 topology file is specified.
 277
 278 Syntax:
 279 ibnetdiscover [options] [<topology-filename>]
 280
 281 Non standard flags:
 282         -l      List of connected nodes
 283         -H      List of connected HCAs
 284         -S      List of connected switches
 285         -g      Grouping
 286
 287 12. ibhosts
 288
 289 Description:
 290 ibhosts either walks the IB subnet topology or uses an already saved topology
 291 file and extracts the CA nodes.
 292
 293 Syntax:
 294 ibhosts [-h] [<topology-file>]
 295
 296 Dependencies:
 297 ibnetdiscover, ibnetdiscover format
 298
 299 13. ibswitches
 300
 301 Description:
 302 ibswitches either walks the IB subnet topology or uses an already saved
 303 topology file and extracts the IB switches.
 304
 305 Syntax:
 306 ibswitches [-h] [<topology-file>]
 307
 308 Dependencies:
 309 ibnetdiscover, ibnetdiscover format
 310
 311 14. ibchecknet
 312
 313 Description:
 314 ibchecknet uses a full topology file that was created by ibnetdiscover,
 315 scans the network to validate the connectivity and reports errors
 316 (from port counters).
 317
 318 Syntax:
 319 ibchecknet [-h] [<topology-file>]
 320
 321 Dependencies:
 322 ibnetdiscover, ibnetdiscover format, ibchecknode, ibcheckport, ibcheckerrs
 323
 324 15. ibcheckport
 325
 326 Description:
 327 Check connectivity and do some simple sanity checks for the specified port.
 328 Port address is lid unless -G option is used to specify a GUID address.
 329
 330 Syntax:
 331 ibcheckport [-h] [-G] <lid|guid> <port_number>
 332
 333 Example:
 334         ibcheckport 2 3         # check lid 2 port 3
 335
 336 Dependencies:
 337 smpquery, smpquery output format, ibaddr
 338
 339 16. ibchecknode
 340
 341 Description:
 342 Check connectivity and do some simple sanity checks for the specified node.
 343 Port address is lid unless -G option is used to specify a GUID address.
 344
 345 Syntax:
 346 ibchecknode [-h] [-G] <lid|guid>
 347
 348 Example:
 349         ibchecknode 2           # check node via lid 2
 350
 351 Dependencies:
 352 smpquery, smpquery output format, ibaddr
 353
 354 Usage:
 355
 356 17. ibcheckerrs
 357
 358 Description:
 359 Check specified port (or node) and report errors that surpassed their predefined
 360 threshold. Port address is lid unless -G option is used to specify a GUID
 361 address. The predefined thresholds can be dumped using the -s option, and a
 362 user defined threshold_file (using the same format as the dump) can be
 363 specified using the -t <file> option.
 364
 365 Syntax:
 366 ibcheckerrs [-h] [-G] [-t <threshold_file>] [-s(how_thresholds)] <lid|guid> [<port>]
 367
 368 Examples:
 369         ibcheckerrs 2           # check aggregated node counter for lid 2
 370         ibcheckerrs 2   4       # check port counters for lid 2 port 4
 371         ibcheckerrs -t xxx 2    # check node using xxx threshold file
 372
 373 Dependencies:
 374 perfquery, perfquery output format, ibaddr
 375
 376 18. ibportstate
 377
 378 Description:
 379 ibportstate allows the port state and port physical state of an IB port
 380 to be queried or a switch port to be disabled or enabled.
 381
 382 Syntax:
 383 ibportstate [-d(ebug) -e(rr_show) -v(erbose) -D(irect) -G(uid) -s smlid
 384 -V(ersion) -C ca_name -P ca_port -t timeout_ms] <dest dr_path|lid|guid>
 385 <portnum> [<op>]
 386         supported ops: enable, disable, query
 387
 388 Examples:
 389         ibportstate 3 1 disable                 # by lid
 390         ibportstate -G 0x2C9000100D051 1 enable # by guid
 391         ibportstate -D 0 1                      # by direct route
 392
 393 19. ibcheckwidth
 394
 395 Description:
 396 ibcheckwidth uses a full topology file that was created by ibnetdiscover,
 397 scans the network to validate the active link widths and reports any 1x
 398 links.
 399
 400 Syntax:
 401 ibcheckwidth [-h] [<topology-file>]
 402
 403 Dependencies:
 404 ibnetdiscover, ibnetdiscover format, ibchecknode, ibcheckportwidth
 405
 406 20. ibcheckportwidth
 407
 408 Description:
 409 Check connectivity and check the specified port for 1x link width.
 410 Port address is lid unless -G option is used to specify a GUID address.
 411
 412 Syntax:
 413 ibcheckportwidth [-h] [-G] <lid|guid> <port>
 414
 415 Example:
 416         ibcheckportwidth 2 3         # check lid 2 port 3
 417
 418 Dependencies:
 419 smpquery, smpquery output format, ibaddr
 420
 421 21. ibcheckstate
 422
 423 Description:
 424 ibcheckstate uses a full topology file that was created by ibnetdiscover,
 425 scans the network to validate the port state and port physical state,
 426 and reports any ports which have a port state other than Active or
 427 a port physical state other than LinkUp.
 428
 429 Syntax:
 430 ibcheckstate [-h] [<topology-file>]
 431
 432 Dependencies:
 433 ibnetdiscover, ibnetdiscover format, ibchecknode, ibcheckportstate
 434
 435 22. ibcheckportstate
 436
 437 Description:
 438 Check connectivity and check the specified port for proper port state
 439 (Active) and port physical state (LinkUp).
 440 Port address is lid unless -G option is used to specify a GUID address.
 441
 442 yntax:
 443 ibcheckportstate [-h] [-G] <lid|guid> <port_number>
 444
 445 Example:
 446         ibcheckportstate 2 3         # check lid 2 port 3
 447
 448 Dependencies:
 449 smpquery, smpquery output format, ibaddr
 450
 451 23. ibcheckerrors
 452
 453 ibcheckerrors uses a full topology file that was created by ibnetdiscover,
 454 scans the network to validate the connectivity and reports errors
 455 (from port counters).
 456
 457 Syntax:
 458 ibnetcheckerrors [-h] [<topology-file>]
 459
 460 Dependencies:
 461 ibnetdiscover, ibnetdiscover format, ibchecknode, ibcheckport, ibcheckerrs
 462
 463 24. ibdiscover.pl
 464
 465 ibdiscover.pl uses a topology file create by ibnetdiscover and a discover.map
 466 file which the network administrator creates which indicates the nodes
 467 to be expected and a ibdiscover.topo file which is the expected connectivity
 468 and produces a new connectivity file (discover.topo.new) and outputs
 469 the changes to stdout. The network administrator can choose to replace
 470 the "old" topo file with the new one or certain changes in.
 471
 472 The syntax of the ibdiscover.map file is:
 473 <nodeGUID>|port|"Text for node"|<NodeDescription from ibnetdiscover format>
 474 e.g.
 475 8f10400410015|8|"ISR 6000"|# SW-6IB4 Voltaire port 0 lid 5
 476 8f10403960558|2|"HCA 1"|# MT23108 InfiniHost Mellanox Technologies
 477
 478 The syntax of the old and new topo files (ibdiscover.topo and
 479 ibdiscover.topo.new) are:
 480 <LocalPort>|<LocalNodeGUID>|<RemotePort>|<RemoteNodeGUID>
 481 e.g.
 482 10|5442ba00003080|1|8f10400410015
 483
 484 These topo files are produced by the ibdiscover.pl tool.
 485
 486 Syntax:
 487 ibnetdiscover | ibdiscover.pl
 488
 489 Dependencies:
 490 ibnetdiscover, ibnetdiscover format
 491
 492 25. ibnodes
 493
 494 Description:
 495 ibnodes either walks the IB subnet topology or uses an already saved topology
 496 file and extracts the IB nodes (CAs and switches).
 497
 498 Syntax:
 499 ibnodes [<topology-file>]
 500
 501 Dependencies:
 502 ibnetdiscover, ibnetdiscover format
 503
 504 26. ibclearerrors
 505
 506 Description:
 507 ibclearerrors clears the PMA error counters in PortCounters by either walking
 508 the IB subnet topology or using an already saved topology file.
 509
 510 Syntax:
 511 ibclearerrors [-h] [<topology-file>]
 512
 513 Dependencies:
 514 ibnetdiscover, ibnetdiscover format, perfquery
 515
 516 27. ibclearcounters
 517
 518 Description:
 519 ibclearcounters clears the PMA port counters by either walking
 520 the IB subnet topology or using an already saved topology file.
 521
 522 Syntax:
 523 ibclearcounters [-h] [<topology-file>]
 524
 525 Dependencies:
 526 ibnetdiscover, ibnetdiscover format, perfquery
 527
 528 28. saquery
 529
 530 Description:
 531 Issue some SA queries.
 532
 533 Syntax:
 534 Usage: saquery [-h -d -P -N -L -G -s -g][<name>]
 535    Queries node records by default
 536    -d enable debugging
 537    -P get PathRecord info
 538    -N get NodeRecord info
 539    -L Return just the Lid of the name specified
 540    -G Return just the Guid of the name specified
 541    -s Return the PortInfoRecords with isSM capability mask bit on
 542    -g get multicast group info
 543
 544 Dependencies:
 545 OpenSM libvendor, OpenSM libopensm, libibumad
 546
 547 29. ibsysstat
 548
 549 Description:
 550 ibsysstat  uses  vendor  mads to validate connectivity between IB nodes
 551 and obtain other information about the IB node.  ibsysstat  is  run  as
 552 client/server. Default is to run as client.
 553
 554 Syntax:
 555 ibsysstat [options] <dest lid|guid> [<op>]
 556
 557 Non standard flags:
 558        Current supported operations:
 559                ping - verify connectivity to server (default)
 560                host - obtain host information from server
 561                cpu  - obtain cpu information from server
 562         -o <oui>        use specified OUI number to multiplex vendor mads
 563         -S              start in server mode (do not return)
 564