.\" .\" *********************************************************************
.\" .\" *                                                                   *
.\" .\" *             Copyright 2015-2019, Intel Corporation                *
.\" .\" *                                                                   *
.\" .\" *                       All Rights Reserved.                        *
.\" .\" *                                                                   *
.\" .\" *********************************************************************

.TH opasaquery 1 "Intel Corporation" "Copyright(C) 2015\-2019" "IFSFFCLIRG (Man Page)"
.SH NAME
opasaquery


.PP

\fB(All)\fR
Performs various queries of the subnet manager/subnet agent and provides detailed fabric information.
.PP
opareport and opareports from the Intel(R) Omni-Path Fabric Suite can provide a more powerful tool. In some cases, opasaquery is preferred, especially when dealing with virtual fabrics, service records, and multicast.
.PP
By default, opasaquery uses the first active port on the local system. However, if the node is connected to more than one fabric (for example, a subnet), the Intel(R) Omni-Path Host Fabric Interface (HFI) and port may be specified to select the fabric whose SA is to be queried.
.SH Syntax
opasaquery [-v [-v] [-v]] [-I] [-h  \fIhfi\fR|-b  \fIaddr\fR] [-p  \fIport\fR] [--timeout]
.br
[-x  \fIgid\fR] [-E]
[-T  \fIssl\(ulparams\fR] [-o  \fItype\fR] [-l  \fIlid\fR] [-t  \fItype\fR] [-s  \fIguid\fR]
.br
[-n  \fIguid\fR]
[-g  \fIguid\fR] [-k  \fIpkey\fR] [-i  \fIvfIndex\fR] [-S  \fIserviceId\fR] [-L  \fIsl\fR]
.br
[-u  \fIgid\fR]
[-m  \fIgid\fR] [-d  \fInodeDescription\fR]  [-D  \fIdg\(ulname\fR]  [-P \[aq]\fIguid guid\fR\[aq]]
.br
[-G \[aq]\fIgid gid\fR\[aq]]
[-H  \fImask\fR]
.SH Options

.TP 10
--help

Produces full help text.

.TP 10
-v/--verbose

Returns verbose output. A second invocation activates openib debugging, a third invocation activates libibumad debugging.

.TP 10
-I/--IB

Issues query in legacy InfiniBand* format.

.TP 10
-h/--hfi \fIhfi\fR

Specifies the HFI, numbered 1..n. Using 0 specifies that the -p \fIport\fR port is a system-wide port number. Default is 0.

.TP 10
-b/--oob \fIaddress\fR

Specifies Out-of-Band address of node running the FE. Can be either hostname, IPv4, or IPv6 address. Default is "127.0.0.1".

.TP 10
-p/--port \fIport\fR

Specifies the port.
.RS

.IP \(bu
In-band: numbered 1..n. Using 0 specifies first active port. Default is 0.
.IP \(bu
Out-of-band: Port FE is listening on. Default is 3245.

.RE


.TP 10
--timeout

Specifies the timeout (wait time for response) in ms. Default is 1000 ms.

.TP 10
-x/--source-gid \fIsrc\(ulgid\fR

Specifies the source GID of the local GID (This is required for most Path and Trace Record Queries when Out-of-Band.)

.TP 10
-E/--feEsm

Specifies the ESM FE.

.TP 10
-T/--ssl-params \fIfile\fR

Specifies the SSL/TLS parameters XML file. Default is /etc/opa/opamgt\(ultls.xml.

.TP 10
-o \fItype\fR

Output type for query. Default is node. See
\fIOutput Types\fR
for details.

.TP 10
-l/--lid \fIlid\fR

Query a specific LID.

.TP 10
-t/--type \fInode\(ultype\fR

Queries by node type. See
\fINode Types\fR
for details.

.TP 10
-s/--sysguid \fIsystem\(ulimage\(ulguid\fR

Queries by system image GUID.

.TP 10
-n/--nodeguid \fInode\(ulguid\fR

Queries by node GUID.

.TP 10
-g/--portguid \fIport\(ulguid\fR

Queries by port GUID.

.TP 10
-k/--pkey \fIpkey\fR

Queries a specific PKey.

.TP 10
-i/--vfindex \fIvfIndex\fR

Queries a specific vfindex.

.TP 10
-S/--serviceId \fIserviceId\fR

Queries a specific service ID.

.TP 10
-L/--SL \fISL\fR

Queries by service level.

.TP 10
-u/--portgid \fIport\(ulgid\fR

Queries by port GID. See
\fIGIDs\fR
for details.

.TP 10
-m/--mcgid \fImulticast\(ulgid\fR

Queries by multicast GID. See
\fIGIDs\fR
for details.

.TP 10
-d/--desc \fInode\(uldescription\fR

Queries by node name/description.

.TP 10
-D/--dgname \fIdg\(ulname\fR

Queries by device group name/description

.TP 10
-P/--guidpair \fIguid guid\fR

Queries by a pair of port GUIDs.

.TP 10
-G/--gidpair \fIgid gid\fR

Queries by a pair of GIDs. See
\fIGIDs\fR
for details.


.SH -h and -p options permit a variety of selections:

.TP 10
-h 0

First active port in system (Default).

.TP 10
-h 0 -p 0

First active port in system.

.TP 10
-h \fIx\fR

First active port on HFI \fIx\fR.

.TP 10
-h \fIx\fR \fI\fR-p 0

First active port on HFI \fIx\fR.

.TP 10
-h 0 -p \fIy\fR

Port \fIy\fR within system (no matter which ports are active).

.TP 10
-h \fIx\fR \fI\fR-p \fIy\fR

HFI \fIx\fR, port \fIy\fR.

.SH Node Types

.TP 10
fi

Fabric Interface

.TP 10
sw

Switch

.SH GIDs

.PP
Specifies a 64-bit subnet and 64-bit interface ID in the form:
.PP
subnet:interface
.PP

.B NOTE:
In the following example, the GID corresponds to a PortGID. In this case, the interface ID coincides with the lower 64-bits of the GUID of the card. The interface ID will be different if the GID is a MGID (that is, multicast GID). See opafm.xml for MGID examples.

.PP

.br
0xfe80000000000000:0x00117500a0000380

.br

.SH Output Types

.PP
Default is node.
.TP 10
classportinfo

Specifies the classportinfo of the SA.

.TP 10
systemguid

Lists the system image GUIDs.

.TP 10
nodeguid

Lists the node GUIDs.

.TP 10
portguid

Lists the port GUIDs.

.TP 10
lid

Lists the LIDs.

.TP 10
desc

Lists the node descriptions/names.

.TP 10
path

Lists the path records.

.TP 10
node

Lists the node records.

.TP 10
portinfo

Lists the port info records.

.TP 10
sminfo

Lists the SM info records.

.TP 10
swinfo

Lists the switch info records.

.TP 10
link

Lists the link records.

.TP 10
scsc

Lists the SC to SC mapping table records.

.TP 10
slsc

Lists the SL to SC mapping table records.

.TP 10
scsl

Lists the SC to SL mapping table records.

.TP 10
scvlt

Lists the SC to VLt table records.

.TP 10
scvlr

Lists the SC to VLr table records.

.TP 10
scvlnt

Lists the SC to VLnt table records.

.TP 10
vlarb

Lists the VL arbitration table records.

.TP 10
pkey

Lists the PKey table records.

.TP 10
service

Lists the service records.

.TP 10
mcmember

Lists the multicast member records.

.TP 10
inform

Lists the inform info records.

.TP 10
linfdb

Lists the switch linear forwarding database (FDB) records.

.TP 10
mcfdb

Lists the switch multicast FDB records.

.TP 10
trace

Lists the trace records.

.TP 10
vfinfo

Lists the vFabrics.

.TP 10
vfinfocsv

Lists the vFabrics in CSV format.

.TP 10
vfinfocsv2

Lists the vFabrics in CSV format with enums.

.TP 10
fabricinfo

Specifies the summary of fabric devices.

.TP 10
quarantine

Lists the quarantined nodes.

.TP 10
conginfo

Lists the Congestion Info Records.

.TP 10
swcongset

Lists the Switch Congestion Settings.

.TP 10
swportcong

Lists the Switch Port Congestion Settings.

.TP 10
hficongset

Lists the HFI Congestion Settings.

.TP 10
hficongcon

Lists the HFI Congestion Control Settings.

.TP 10
bfrctrl

Lists the buffer control tables.

.TP 10
cableinfo

Lists the Cable Info records.

.TP 10
portgroup

Lists the AR Port Group records.

.TP 10
portgroupfdb

Lists the AR Port Group FWD records.

.TP 10
dglist

Lists the Device Group Names.

.TP 10
dgmember

Lists the Device Group records.

.TP 10
dtree

Lists the Device Tree records.

.TP 10
swcost

Lists the switch cost records.

.PP
The vfinfocsv and vfinfocsv2 output formats are designed to make it easier to script vfinfo queries. One line is output per vFabric of the form:
.PP

.br

.br
name:index:pkey:sl:mtu:rate:optionflag::mcastSl

.br

.PP
The only difference between these two formats is how the MTU and rate are output. vfinfocsv outputs MTU and rate in human/text readable format. vfinfocsv2 outputs MTU and rate as enumerations defined for the SMA protocol. The opagetvf command is based on this capability of opasaquery. For more information, see
\fIopagetvf\fR
.
.SH Example
opasaquery -o desc -t fi

.SH Input Options vs. Output Permitted

.PP
The following list shows the input (assorted query by options) and outputs (-o) that are permitted.
.TP 10
None


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, path, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, vfinfo, vfinfocsv, vfinfocsv2, scsc, slsc, scvlt, scnlmt, linfdb, classportinfo, fabricinfo, quarantine, conginfo, swcongset, swportcong, hficongset, hficongcon, bfrctl, cableinfo, portgroup, portgroupfdb, dglist, dgmember, dtree

.RE

.RS
.TP 10

.sp
-o output not permitted
trace

.RE


.TP 10
-t \fInode\(ultype\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, node, dglist, dgmember, dtree

.RE

.RS
.TP 10

.sp
-o output not permitted
portinfo, sminfo, swinfo, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, trace, vfinfo, vfinfocsv, vfinfocsv2

.RE


.TP 10
-l \fIlid\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, path, node, portinfo, swinfo, slvl, vlarb, pkey, mcmember, linfdb, mcfdb, dgmember, dtree

.RE

.RS
.TP 10

.sp
-o output not permitted
sminfo, link, inform, service, trace, vfinfo, vfinfocsv, vfinfocsv2, dglist

.RE


.TP 10
-k \fIpkey\fR


.RS
.TP 10

.sp
-o output permitted
mcmember, path, vfinfo, vfinfocsv, vfinfocsv2

.RE

.RS
.TP 10

.sp
-o output not permitted
systemimageguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-i
\fIvfindex\fR




.RS
.TP 10

.sp
-o output permitted
vfinfo, vfinfocsv, vfinfocsv2

.RE

.RS
.TP 10

.sp
-o output not permitted
systemimageguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-s \fIsystem\(ulimage\(ulguid\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, node

.RE

.RS
.TP 10

.sp
-o output not permitted
portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, trace, vfinfo, vfinfocsv, vfinfocsv2, dglist, dgmember, dtree

.RE


.TP 10
-n \fInode\(ulguid\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, node

.RE

.RS
.TP 10

.sp
-o output not permitted
portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, trace, vfinfo, vfinfocsv, vfinfocsv2, dglist, dgmember, dtree

.RE


.TP 10
-g \fIport\(ulguid\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, path, node, trace, dgmember

.RE

.RS
.TP 10

.sp
-o output not permitted
portinfo, sminfo, swinfo, link, vlarb, pkey, linfdb, mcfdb, vfinfo, vfinfocsv, vfinfocsv2, dglist, dtree, service, mcmember, inform

.RE


.TP 10
-u \fIport\(ulgid\fR


.RS
.TP 10

.sp
-o output permitted
path, service, mcmember, inform, trace

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, linfdb, mcfdb, vfinfo, vfinfocsv, vfinfocsv2, dglist, dgmember, dtree

.RE


.TP 10
-m \fImulticast\(ulgid\fR


.RS
.TP 10

.sp
-o output permitted
mcmember, vfinfo, vfinfocsv, vfinfocsv2

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, path, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, inform, linfdb, mcfdb, trace, dglist, dgmember, dtree

.RE


.TP 10
-d \fInode\(uldescription\fR


.RS
.TP 10

.sp
-o output permitted
systemguid, nodeguid, portguid, lid, desc, node, dgmember

.RE

.RS
.TP 10

.sp
-o output not permitted
trace, dglist, dtree

.RE


.TP 10
-D \fIdg\(ulname\fR


.RS
.TP 10

.sp
-o output permitted
dgmember

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, path, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, inform, linfdb, mcfdb, trace, dglist, dtree

.RE


.TP 10
-P \fIport\(ulguid\(ulpair\fR


.RS
.TP 10

.sp
-o output permitted
path, trace

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-S \fIserviceId\fR


.RS
.TP 10

.sp
-o output permitted
path, vfinfo, vfinfocsv, vfinfocsv2, service

.RE

.RS
.TP 10

.sp
-o output not permitted
systemimageguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-L \fISL\fR


.RS
.TP 10

.sp
-o output permitted
path, vfinfo, vfinfocsv, vfinfocsv2

.RE

.RS
.TP 10

.sp
-o output not permitted
systemimageguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-G \fIgid\(ulpair\fR


.RS
.TP 10

.sp
-o output permitted
path, trace

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, dglist, dgmember, dtree

.RE


.TP 10
-a \fIport\(ulguid\(ullist\fR


.RS
.TP 10

.sp
-o output permitted
path

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, trace, dglist, dgmember, dtree

.RE


.TP 10
-A \fIgid\(ullist\fR


.RS
.TP 10

.sp
-o output permitted
path

.RE

.RS
.TP 10

.sp
-o output not permitted
systemguid, nodeguid, portguid, lid, desc, node, portinfo, sminfo, swinfo, link, vlarb, pkey, service, mcmember, inform, linfdb, mcfdb, trace, dglist, dgmember, dtree

.RE