contrib/ofed/infiniband-diags/man/ibnetdiscover.8

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH IBNETDISCOVER 8 "" "" "Open IB Diagnostics"
   4 .SH NAME
   5 IBNETDISCOVER \- discover InfiniBand topology
   6 .
   7 .nr rst2man-indent-level 0
   8 .
   9 .de1 rstReportMargin
  10 \\$1 \\n[an-margin]
  11 level \\n[rst2man-indent-level]
  12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13 -
  14 \\n[rst2man-indent0]
  15 \\n[rst2man-indent1]
  16 \\n[rst2man-indent2]
  17 ..
  18 .de1 INDENT
  19 .\" .rstReportMargin pre:
  20 . RS \\$1
  21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22 . nr rst2man-indent-level +1
  23 .\" .rstReportMargin post:
  24 ..
  25 .de UNINDENT
  26 . RE
  27 .\" indent \\n[an-margin]
  28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .nr rst2man-indent-level -1
  30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32 ..
  33 .SH SYNOPSIS
  34 .sp
  35 ibnetdiscover [options] [<topology\-file>]
  36 .SH DESCRIPTION
  37 .sp
  38 ibnetdiscover performs IB subnet discovery and outputs a human readable
  39 topology file. GUIDs, node types, and port numbers are displayed
  40 as well as port LIDs and NodeDescriptions.  All nodes (and links) are displayed
  41 (full topology).  Optionally, this utility can be used to list the current
  42 connected nodes by nodetype.  The output is printed to standard output
  43 unless a topology file is specified.
  44 .SH OPTIONS
  45 .sp
  46 \fB\-l, \-\-list\fP
  47 List of connected nodes
  48 .sp
  49 \fB\-g, \-\-grouping\fP
  50 Show grouping.  Grouping correlates IB nodes by different vendor specific
  51 schemes.  It may also show the switch external ports correspondence.
  52 .sp
  53 \fB\-H, \-\-Hca_list\fP
  54 List of connected CAs
  55 .sp
  56 \fB\-S, \-\-Switch_list\fP
  57 List of connected switches
  58 .sp
  59 \fB\-R, \-\-Router_list\fP
  60 List of connected routers
  61 .sp
  62 \fB\-s, \-\-show\fP
  63 Show progress information during discovery.
  64 .sp
  65 \fB\-f, \-\-full\fP
  66 Show full information (ports\(aq speed and width, vlcap)
  67 .sp
  68 \fB\-p, \-\-ports\fP
  69 Obtain a ports report which is a
  70 list of connected ports with relevant information (like LID, portnum,
  71 GUID, width, speed, and NodeDescription).
  72 .sp
  73 \fB\-m, \-\-max_hops\fP
  74 Report max hops discovered.
  75 .\" Define the common option -z
  76 .
  77 .INDENT 0.0
  78 .TP
  79 .B \fB\-\-outstanding_smps, \-o <val>\fP
  80 Specify the number of outstanding SMP\(aqs which should be issued during the scan
  81 .sp
  82 Default: 2
  83 .UNINDENT
  84 .SS Cache File flags
  85 .\" Define the common option cache
  86 .
  87 .sp
  88 \fB\-\-cache <filename>\fP
  89 Cache the ibnetdiscover network data in the specified filename.  This
  90 cache may be used by other tools for later analysis.
  91 .\" Define the common option load-cache
  92 .
  93 .sp
  94 \fB\-\-load\-cache <filename>\fP
  95 Load and use the cached ibnetdiscover data stored in the specified
  96 filename.  May be useful for outputting and learning about other
  97 fabrics or a previous state of a fabric.
  98 .\" Define the common option diff
  99 .
 100 .sp
 101 \fB\-\-diff <filename>\fP
 102 Load cached ibnetdiscover data and do a diff comparison to the current
 103 network or another cache.  A special diff output for ibnetdiscover
 104 output will be displayed showing differences between the old and current
 105 fabric.  By default, the following are compared for differences: switches,
 106 channel adapters, routers, and port connections.
 107 .\" Define the common option diffcheck
 108 .
 109 .sp
 110 \fB\-\-diffcheck <key(s)>\fP
 111 Specify what diff checks should be done in the \fB\-\-diff\fP option above.
 112 Comma separate multiple diff check key(s).  The available diff checks
 113 are: \fBsw = switches\fP, \fBca = channel adapters\fP, \fBrouter\fP = routers,
 114 \fBport\fP = port connections, \fBlid\fP = lids, \fBnodedesc\fP = node
 115 descriptions.  Note that \fBport\fP, \fBlid\fP, and \fBnodedesc\fP are
 116 checked only for the node types that are specified (e.g. \fBsw\fP,
 117 \fBca\fP, \fBrouter\fP).  If \fBport\fP is specified alongside \fBlid\fP
 118 or \fBnodedesc\fP, remote port lids and node descriptions will also be compared.
 119 .SS Port Selection flags
 120 .\" Define the common option -C
 121 .
 122 .sp
 123 \fB\-C, \-\-Ca <ca_name>\fP    use the specified ca_name.
 124 .\" Define the common option -P
 125 .
 126 .sp
 127 \fB\-P, \-\-Port <ca_port>\fP    use the specified ca_port.
 128 .\" Explanation of local port selection
 129 .
 130 .SS Local port Selection
 131 .sp
 132 Multiple port/Multiple CA support: when no IB device or port is specified
 133 (see the "local umad parameters" below), the libibumad library
 134 selects the port to use by the following criteria:
 135 .INDENT 0.0
 136 .INDENT 3.5
 137 .INDENT 0.0
 138 .IP 1. 3
 139 the first port that is ACTIVE.
 140 .IP 2. 3
 141 if not found, the first port that is UP (physical link up).
 142 .UNINDENT
 143 .sp
 144 If a port and/or CA name is specified, the libibumad library attempts
 145 to fulfill the user request, and will fail if it is not possible.
 146 .sp
 147 For example:
 148 .INDENT 0.0
 149 .INDENT 3.5
 150 .sp
 151 .nf
 152 .ft C
 153 ibaddr                 # use the first port (criteria #1 above)
 154 ibaddr \-C mthca1       # pick the best port from "mthca1" only.
 155 ibaddr \-P 2            # use the second (active/up) port from the first available IB device.
 156 ibaddr \-C mthca0 \-P 2  # use the specified port only.
 157 .ft P
 158 .fi
 159 .UNINDENT
 160 .UNINDENT
 161 .UNINDENT
 162 .UNINDENT
 163 .SS Configuration flags
 164 .\" Define the common option -z
 165 .
 166 .sp
 167 \fB\-\-config, \-z  <config_file>\fP Specify alternate config file.
 168 .INDENT 0.0
 169 .INDENT 3.5
 170 Default: /etc/infiniband-diags/ibdiag.conf
 171 .UNINDENT
 172 .UNINDENT
 173 .\" Define the common option -z
 174 .
 175 .INDENT 0.0
 176 .TP
 177 .B \fB\-\-outstanding_smps, \-o <val>\fP
 178 Specify the number of outstanding SMP\(aqs which should be issued during the scan
 179 .sp
 180 Default: 2
 181 .UNINDENT
 182 .\" Define the common option --node-name-map
 183 .
 184 .sp
 185 \fB\-\-node\-name\-map <node\-name\-map>\fP Specify a node name map.
 186 .INDENT 0.0
 187 .INDENT 3.5
 188 This file maps GUIDs to more user friendly names.  See FILES section.
 189 .UNINDENT
 190 .UNINDENT
 191 .\" Define the common option -t
 192 .
 193 .sp
 194 \fB\-t, \-\-timeout <timeout_ms>\fP override the default timeout for the solicited mads.
 195 .\" Define the common option -y
 196 .
 197 .INDENT 0.0
 198 .TP
 199 .B \fB\-y, \-\-m_key <key>\fP
 200 use the specified M_key for requests. If non\-numeric value (like \(aqx\(aq)
 201 is specified then a value will be prompted for.
 202 .UNINDENT
 203 .SS Debugging flags
 204 .\" Define the common option -d
 205 .
 206 .INDENT 0.0
 207 .TP
 208 .B \-d
 209 raise the IB debugging level.
 210 May be used several times (\-ddd or \-d \-d \-d).
 211 .UNINDENT
 212 .\" Define the common option -e
 213 .
 214 .INDENT 0.0
 215 .TP
 216 .B \-e
 217 show send and receive errors (timeouts and others)
 218 .UNINDENT
 219 .\" Define the common option -h
 220 .
 221 .sp
 222 \fB\-h, \-\-help\fP      show the usage message
 223 .\" Define the common option -v
 224 .
 225 .INDENT 0.0
 226 .TP
 227 .B \fB\-v, \-\-verbose\fP
 228 increase the application verbosity level.
 229 May be used several times (\-vv or \-v \-v \-v)
 230 .UNINDENT
 231 .\" Define the common option -V
 232 .
 233 .sp
 234 \fB\-V, \-\-version\fP     show the version info.
 235 .SH FILES
 236 .\" Common text for the config file
 237 .
 238 .SS CONFIG FILE
 239 .sp
 240 /etc/infiniband-diags/ibdiag.conf
 241 .sp
 242 A global config file is provided to set some of the common options for all
 243 tools.  See supplied config file for details.
 244 .\" Common text to describe the node name map file.
 245 .
 246 .SS NODE NAME MAP FILE FORMAT
 247 .sp
 248 The node name map is used to specify user friendly names for nodes in the
 249 output.  GUIDs are used to perform the lookup.
 250 .sp
 251 This functionality is provided by the opensm\-libs package.  See \fBopensm(8)\fP
 252 for the file location for your installation.
 253 .sp
 254 \fBGenerically:\fP
 255 .INDENT 0.0
 256 .INDENT 3.5
 257 .sp
 258 .nf
 259 .ft C
 260 # comment
 261 <guid> "<name>"
 262 .ft P
 263 .fi
 264 .UNINDENT
 265 .UNINDENT
 266 .sp
 267 \fBExample:\fP
 268 .INDENT 0.0
 269 .INDENT 3.5
 270 .sp
 271 .nf
 272 .ft C
 273 # IB1
 274 # Line cards
 275 0x0008f104003f125c "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB\-24D"
 276 0x0008f104003f125d "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB\-24D"
 277 0x0008f104003f10d2 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB\-24D"
 278 0x0008f104003f10d3 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB\-24D"
 279 0x0008f104003f10bf "IB1 (Rack 11 slot 12  ) ISR9288/ISR9096 Voltaire sLB\-24D"
 280
 281 # Spines
 282 0x0008f10400400e2d "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB\-12D"
 283 0x0008f10400400e2e "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB\-12D"
 284 0x0008f10400400e2f "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB\-12D"
 285 0x0008f10400400e31 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB\-12D"
 286 0x0008f10400400e32 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB\-12D"
 287
 288 # GUID   Node Name
 289 0x0008f10400411a08 "SW1  (Rack  3) ISR9024 Voltaire 9024D"
 290 0x0008f10400411a28 "SW2  (Rack  3) ISR9024 Voltaire 9024D"
 291 0x0008f10400411a34 "SW3  (Rack  3) ISR9024 Voltaire 9024D"
 292 0x0008f104004119d0 "SW4  (Rack  3) ISR9024 Voltaire 9024D"
 293 .ft P
 294 .fi
 295 .UNINDENT
 296 .UNINDENT
 297 .\" Common text to describe the Topology file.
 298 .
 299 .SS TOPOLOGY FILE FORMAT
 300 .sp
 301 The topology file format is human readable and largely intuitive.
 302 Most identifiers are given textual names like vendor ID (vendid), device ID
 303 (device ID), GUIDs of various types (sysimgguid, caguid, switchguid, etc.).
 304 PortGUIDs are shown in parentheses ().  For switches, this is shown on the
 305 switchguid line.  For CA and router ports, it is shown on the connectivity
 306 lines.  The IB node is identified followed by the number of ports and a quoted
 307 the node GUID.  On the right of this line is a comment (#) followed by the
 308 NodeDescription in quotes.  If the node is a switch, this line also contains
 309 whether switch port 0 is base or enhanced, and the LID and LMC of port 0.
 310 Subsequent lines pertaining to this node show the connectivity.   On the
 311 left is the port number of the current node.  On the right is the peer node
 312 (node at other end of link). It is identified in quotes with nodetype
 313 followed by \- followed by NodeGUID with the port number in square brackets.
 314 Further on the right is a comment (#).  What follows the comment is
 315 dependent on the node type.  If it it a switch node, it is followed by
 316 the NodeDescription in quotes and the LID of the peer node.  If it is a
 317 CA or router node, it is followed by the local LID and LMC and then
 318 followed by the NodeDescription in quotes and the LID of the peer node.
 319 The active link width and speed are then appended to the end of this
 320 output line.
 321 .sp
 322 An example of this is:
 323 .INDENT 0.0
 324 .INDENT 3.5
 325 .sp
 326 .nf
 327 .ft C
 328 #
 329 # Topology file: generated on Tue Jun  5 14:15:10 2007
 330 #
 331 # Max of 3 hops discovered
 332 # Initiated from node 0008f10403960558 port 0008f10403960559
 333
 334 Non\-Chassis Nodes
 335
 336 vendid=0x8f1
 337 devid=0x5a06
 338 sysimgguid=0x5442ba00003000
 339 switchguid=0x5442ba00003080(5442ba00003080)
 340 Switch  24 "S\-005442ba00003080"         # "ISR9024 Voltaire" base port 0 lid 6 lmc 0
 341 [22]    "H\-0008f10403961354"[1](8f10403961355)         # "MT23108 InfiniHost Mellanox Technologies" lid 4 4xSDR
 342 [10]    "S\-0008f10400410015"[1]         # "SW\-6IB4 Voltaire" lid 3 4xSDR
 343 [8]     "H\-0008f10403960558"[2](8f1040396055a)         # "MT23108 InfiniHost Mellanox Technologies" lid 14 4xSDR
 344 [6]     "S\-0008f10400410015"[3]         # "SW\-6IB4 Voltaire" lid 3 4xSDR
 345 [12]    "H\-0008f10403960558"[1](8f10403960559)         # "MT23108 InfiniHost Mellanox Technologies" lid 10 4xSDR
 346
 347 vendid=0x8f1
 348 devid=0x5a05
 349 switchguid=0x8f10400410015(8f10400410015)
 350 Switch  8 "S\-0008f10400410015"          # "SW\-6IB4 Voltaire" base port 0 lid 3 lmc 0
 351 [6]     "H\-0008f10403960984"[1](8f10403960985)         # "MT23108 InfiniHost Mellanox Technologies" lid 16 4xSDR
 352 [4]     "H\-005442b100004900"[1](5442b100004901)        # "MT23108 InfiniHost Mellanox Technologies" lid 12 4xSDR
 353 [1]     "S\-005442ba00003080"[10]                # "ISR9024 Voltaire" lid 6 1xSDR
 354 [3]     "S\-005442ba00003080"[6]         # "ISR9024 Voltaire" lid 6 4xSDR
 355
 356 vendid=0x2c9
 357 devid=0x5a44
 358 caguid=0x8f10403960984
 359 Ca      2 "H\-0008f10403960984"          # "MT23108 InfiniHost Mellanox Technologies"
 360 [1](8f10403960985)     "S\-0008f10400410015"[6]         # lid 16 lmc 1 "SW\-6IB4 Voltaire" lid 3 4xSDR
 361
 362 vendid=0x2c9
 363 devid=0x5a44
 364 caguid=0x5442b100004900
 365 Ca      2 "H\-005442b100004900"          # "MT23108 InfiniHost Mellanox Technologies"
 366 [1](5442b100004901)     "S\-0008f10400410015"[4]         # lid 12 lmc 1 "SW\-6IB4 Voltaire" lid 3 4xSDR
 367
 368 vendid=0x2c9
 369 devid=0x5a44
 370 caguid=0x8f10403961354
 371 Ca      2 "H\-0008f10403961354"          # "MT23108 InfiniHost Mellanox Technologies"
 372 [1](8f10403961355)     "S\-005442ba00003080"[22]                # lid 4 lmc 1 "ISR9024 Voltaire" lid 6 4xSDR
 373
 374 vendid=0x2c9
 375 devid=0x5a44
 376 caguid=0x8f10403960558
 377 Ca      2 "H\-0008f10403960558"          # "MT23108 InfiniHost Mellanox Technologies"
 378 [2](8f1040396055a)     "S\-005442ba00003080"[8]         # lid 14 lmc 1 "ISR9024 Voltaire" lid 6 4xSDR
 379 [1](8f10403960559)     "S\-005442ba00003080"[12]                # lid 10 lmc 1 "ISR9024 Voltaire" lid 6 1xSDR
 380 .ft P
 381 .fi
 382 .UNINDENT
 383 .UNINDENT
 384 .sp
 385 When grouping is used, IB nodes are organized into chassis which are
 386 numbered. Nodes which cannot be determined to be in a chassis are
 387 displayed as "Non\-Chassis Nodes".  External ports are also shown on the
 388 connectivity lines.
 389 .SH AUTHORS
 390 .INDENT 0.0
 391 .TP
 392 .B Hal Rosenstock
 393 < \fI\%halr@voltaire.com\fP >
 394 .TP
 395 .B Ira Weiny
 396 < \fI\%ira.weiny@intel.com\fP >
 397 .UNINDENT
 398 .\" Generated by docutils manpage writer.
 399 .