infiniband-diags

title: infiniband-diags(8)

summary: Diagnostics for InfiniBand Fabrics

text:
# infiniband-diags(8)

## NAME
infiniband-diags - Diagnostics for InfiniBand Fabrics

## DESCRIPTION
infiniband-diags is a set of utilities designed to help configure, debug, and maintain infiniband fabrics. Many tools and utilities are provided. Some with similar functionality.

The base utilities use directed route MAD's to perform their operations. They may therefore work even in unconfigured subnets. Other, higher level utilities, require LID routed MAD's and to some extent SA/SM access.

## THE USE OF SMPS (QP0)
Many of the tools in this package rely on the use of SMPs via QP0 to acquire data directly from the SMA. While this mode of operation is not technically in compliance with the InfiniBand specification, practical experience has found that this level of diagnostics is valuable when working with a fabric which is broken or only partially configured. For this reason many of these tools may require the use of an MKey or operation from Virtual Machines may be restricted for security reasons.

## COMMON OPTIONS
Most OpenIB diagnostics take some of the following common flags. The exact list of supported flags per utility can be found in the documentation for those commands.

### Addressing Flags
The -D and -G option have two forms:

-D, --Direct The address specified is a directed route

```
Examples:

   [options] -D [options] "0"          # self port

   [options] -D [options] "0,1,2,1,4"  # out via port 1, then 2, ...

   (Note the second number in the path specified must match the port being

   used.  This can be specified using the port selection flag '-P' or the

   port found through the automatic selection process.)
```

-D, --Direct <dr_path> The address specified is a directed route

```
Examples:

   -D "0"          # self port

   -D "0,1,2,1,4"  # out via port 1, then 2, ...

   (Note the second number in the path specified must match the port being

   used.  This can be specified using the port selection flag '-P' or the

   port found through the automatic selection process.)
```

-G, --Guid The address specified is a Port GUID

--port-guid, -G <port_guid> Specify a port_guid

-L, --Lid The address specified is a LID

-s, --sm_port <smlid> use 'smlid' as the target lid for SA queries.

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

--outstanding_smps, -o <val>

Specify the number of outstanding SMP's which should be issued during the scan Default: 2

--node-name-map <node-name-map> Specify a node name map.

This file maps GUIDs to more user friendly names. See FILES section.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## COMMON FILES
The following config files are common amongst many of the utilities.

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

### NODE NAME MAP FILE FORMAT
The node name map is used to specify user friendly names for nodes in the output. GUIDs are used to perform the lookup.

This functionality is provided by the opensm-libs package. See opensm(8) for the file location for your installation.

Generically:

```
# comment
<guid> "<name>"
```

Example:

```
# IB1
# Line cards
0x0008f104003f125c "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f125d "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d2 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d3 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10bf "IB1 (Rack 11 slot 12  ) ISR9288/ISR9096 Voltaire sLB-24D"
# Spines
0x0008f10400400e2d "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2e "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2f "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e31 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e32 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
# GUID   Node Name
0x0008f10400411a08 "SW1  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a28 "SW2  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a34 "SW3  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f104004119d0 "SW4  (Rack  3) ISR9024 Voltaire 9024D"
```

### TOPOLOGY FILE FORMAT
The topology file format is human readable and largely intuitive. Most identifiers are given textual names like vendor ID (vendid), device ID (device ID), GUIDs of various types (sysimgguid, caguid, switchguid, etc.). PortGUIDs are shown in parentheses (). For switches, this is shown on the switchguid line. For CA and router ports, it is shown on the connectivity lines. The IB node is identified followed by the number of ports and a quoted the node GUID. On the right of this line is a comment (#) followed by the NodeDescription in quotes. If the node is a switch, this line also contains whether switch port 0 is base or enhanced, and the LID and LMC of port 0. Subsequent lines pertaining to this node show the connectivity. On the left is the port number of the current node. On the right is the peer node (node at other end of link). It is identified in quotes with nodetype followed by - followed by NodeGUID with the port number in square brackets. Further on the right is a comment (#). What follows the comment is dependent on the node type. If it it a switch node, it is followed by the NodeDescription in quotes and the LID of the peer node. If it is a CA or router node, it is followed by the local LID and LMC and then followed by the NodeDescription in quotes and the LID of the peer node. The active link width and speed are then appended to the end of this output line.

An example of this is:

```
#
# Topology file: generated on Tue Jun  5 14:15:10 2007
#
# Max of 3 hops discovered
# Initiated from node 0008f10403960558 port 0008f10403960559
Non-Chassis Nodes
vendid=0x8f1
devid=0x5a06
sysimgguid=0x5442ba00003000
switchguid=0x5442ba00003080(5442ba00003080)
Switch  24 "S-005442ba00003080"         # "ISR9024 Voltaire" base port 0 lid 6 lmc 0
[22]    "H-0008f10403961354"[1](8f10403961355)         # "MT23108 InfiniHost Mellanox Technologies" lid 4 4xSDR
[10]    "S-0008f10400410015"[1]         # "SW-6IB4 Voltaire" lid 3 4xSDR
[8]     "H-0008f10403960558"[2](8f1040396055a)         # "MT23108 InfiniHost Mellanox Technologies" lid 14 4xSDR
[6]     "S-0008f10400410015"[3]         # "SW-6IB4 Voltaire" lid 3 4xSDR
[12]    "H-0008f10403960558"[1](8f10403960559)         # "MT23108 InfiniHost Mellanox Technologies" lid 10 4xSDR
vendid=0x8f1
devid=0x5a05
switchguid=0x8f10400410015(8f10400410015)
Switch  8 "S-0008f10400410015"          # "SW-6IB4 Voltaire" base port 0 lid 3 lmc 0
[6]     "H-0008f10403960984"[1](8f10403960985)         # "MT23108 InfiniHost Mellanox Technologies" lid 16 4xSDR
[4]     "H-005442b100004900"[1](5442b100004901)        # "MT23108 InfiniHost Mellanox Technologies" lid 12 4xSDR
[1]     "S-005442ba00003080"[10]                # "ISR9024 Voltaire" lid 6 1xSDR
[3]     "S-005442ba00003080"[6]         # "ISR9024 Voltaire" lid 6 4xSDR
vendid=0x2c9
devid=0x5a44
caguid=0x8f10403960984
Ca      2 "H-0008f10403960984"          # "MT23108 InfiniHost Mellanox Technologies"
[1](8f10403960985)     "S-0008f10400410015"[6]         # lid 16 lmc 1 "SW-6IB4 Voltaire" lid 3 4xSDR
vendid=0x2c9
devid=0x5a44
caguid=0x5442b100004900
Ca      2 "H-005442b100004900"          # "MT23108 InfiniHost Mellanox Technologies"
[1](5442b100004901)     "S-0008f10400410015"[4]         # lid 12 lmc 1 "SW-6IB4 Voltaire" lid 3 4xSDR
vendid=0x2c9
devid=0x5a44
caguid=0x8f10403961354
Ca      2 "H-0008f10403961354"          # "MT23108 InfiniHost Mellanox Technologies"
[1](8f10403961355)     "S-005442ba00003080"[22]                # lid 4 lmc 1 "ISR9024 Voltaire" lid 6 4xSDR
vendid=0x2c9
devid=0x5a44
caguid=0x8f10403960558
Ca      2 "H-0008f10403960558"          # "MT23108 InfiniHost Mellanox Technologies"
[2](8f1040396055a)     "S-005442ba00003080"[8]         # lid 14 lmc 1 "ISR9024 Voltaire" lid 6 4xSDR
[1](8f10403960559)     "S-005442ba00003080"[12]                # lid 10 lmc 1 "ISR9024 Voltaire" lid 6 1xSDR
```

When grouping is used, IB nodes are organized into chassis which are numbered. Nodes which cannot be determined to be in a chassis are displayed as "Non-Chassis Nodes". External ports are also shown on the connectivity lines.

## UTILITIES LIST

### Basic fabric connectivity
See: ibnetdiscover, iblinkinfo

### Node information
See: ibnodes, ibswitches, ibhosts, ibrouters

### Port information
See: ibportstate, ibaddr

### Switch Forwarding Table info
See: ibtracert, ibroute, dump_lfts, dump_mfts, check_lft_balance, ibfindnodesusing

### Performance counters
See: ibqueryerrors, perfquery

### Local HCA info
See: ibstat, ibstatus

### Connectivity check
See: ibping, ibsysstat

### Low level query tools
See: smpquery, smpdump, saquery, sminfo

### Fabric verification tools
See: ibidsverify

## BACKWARDS COMPATIBILITY SCRIPTS
The following scripts have been identified as redundant and/or lower performing as compared to the above scripts. They are provided as legacy scripts when --enable-compat-utils is specified at build time.

ibcheckerrors, ibclearcounters, ibclearerrors, ibdatacounters ibchecknet, ibchecknode, ibcheckport, ibcheckportstate, ibcheckportwidth, ibcheckstate, ibcheckwidth, ibswportwatch, ibprintca, ibprintrt, ibprintswitch, set_nodedesc.sh

## AUTHORS
Ira Weiny

< ira.weiny@intel.com >


perfquery

package: infiniband-diags

title: perfquery(8)

text:
# perfquery(8)

## NAME
perfquery - query InfiniBand port counters on a single port

## SYNOPSIS
perfquery [options] [<lid|guid> [[port(s)] [reset_mask]]]

## DESCRIPTION
perfquery uses PerfMgt GMPs to obtain the PortCounters (basic performance and error counters), PortExtendedCounters, PortXmitDataSL, PortRcvDataSL, PortRcvErrorDetails, PortXmitDiscardDetails, PortExtendedSpeedsCounters, or PortSamplesControl from the PMA at the node/port specified. Optionally shows aggregated counters for all ports of node. Finally it can, reset after read, or just reset the counters.

Note: In PortCounters, PortCountersExtended, PortXmitDataSL, and PortRcvDataSL, components that represent Data (e.g. PortXmitData and PortRcvData) indicate octets divided by 4 rather than just octets.

Note: Inputting a port of 255 indicates an operation be performed on all ports.

Note: For PortCounters, ExtendedCounters, and resets, multiple ports can be specified by either a comma separated list or a port range. See examples below.

## OPTIONS
-x, --extended

show extended port counters rather than (basic) port counters. Note that extended port counters attribute is optional.

-X, --xmtsl

show transmit data SL counter. This is an optional counter for QoS.

-S, --rcvsl

show receive data SL counter. This is an optional counter for QoS.

-D, --xmtdisc

show transmit discard details. This is an optional counter.

-E, --rcverr

show receive error details. This is an optional counter.

-D, --xmtdisc

show transmit discard details. This is an optional counter.

-T, --extended_speeds

show extended speeds port counters. This is an optional counter.

--oprcvcounters

show Rcv Counters per Op code. This is an optional counter.

--flowctlcounters

show flow control counters. This is an optional counter.

--vloppackets

show packets received per Op code per VL. This is an optional counter.

--vlopdata

show data received per Op code per VL. This is an optional counter.

--vlxmitflowctlerrors

show flow control update errors per VL. This is an optional counter.

--vlxmitcounters

show ticks waiting to transmit counters per VL. This is an optional counter.

--swportvlcong

show sw port VL congestion. This is an optional counter.

--rcvcc

show Rcv congestion control counters. This is an optional counter.

--slrcvfecn

show SL Rcv FECN counters. This is an optional counter.

--slrcvbecn

show SL Rcv BECN counters. This is an optional counter.

--xmitcc

show Xmit congestion control counters. This is an optional counter.

--vlxmittimecc

show VL Xmit Time congestion control counters. This is an optional counter.

-c, --smplctl

show port samples control.

-a, --all_ports

show aggregated counters for all ports of the destination lid, reset all counters for all ports, or if multiple ports are specified, aggregate the counters of the specified ports. If the destination lid does not support the AllPortSelect flag, all ports will be iterated through to emulate AllPortSelect behavior.

-l, --loop_ports

If all ports are selected by the user (either through the -a option or port 255) or multiple ports are specified iterate through each port rather than doing than aggregate operation.

-r, --reset_after_read

reset counters after read

-R, --Reset_only

only reset counters

### Addressing Flags
-G, --Guid The address specified is a Port GUID

-L, --Lid The address specified is a LID

-s, --sm_port <smlid> use 'smlid' as the target lid for SA queries.

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

-y, --m_key <key>

use the specified M_key for requests. If non-numeric value (like 'x') is specified then a value will be prompted for.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

## EXAMPLES

```
perfquery                # read local port performance counters
perfquery 32 1           # read performance counters from lid 32, port 1
perfquery -x 32 1        # read extended performance counters from lid 32, port 1
perfquery -a 32          # read perf counters from lid 32, all ports
perfquery -r 32 1        # read performance counters and reset
perfquery -x -r 32 1     # read extended performance counters and reset
perfquery -R 0x20 1      # reset performance counters of port 1 only
perfquery -x -R 0x20 1   # reset extended performance counters of port 1 only
perfquery -R -a 32       # reset performance counters of all ports
perfquery -R 32 2 0x0fff # reset only error counters of port 2
perfquery -R 32 2 0xf000 # reset only non-error counters of port 2
perfquery -a 32 1-10     # read performance counters from lid 32, port 1-10, aggregate output
perfquery -l 32 1-10     # read performance counters from lid 32, port 1-10, output each port
perfquery -a 32 1,4,8    # read performance counters from lid 32, port 1, 4, and 8, aggregate output
perfquery -l 32 1,4,8    # read performance counters from lid 32, port 1, 4, and 8, output each port
```

## AUTHOR
Hal Rosenstock

< hal.rosenstock@gmail.com >


saquery

title: saquery(8)

text:
# saquery(8)

## NAME
saquery - query InfiniBand subnet administration attributes

## SYNOPSIS
saquery [options] [<name> | <lid> | <guid>]

## DESCRIPTION
saquery issues the selected SA query. Node records are queried by default.

## OPTIONS
-p

get PathRecord info

-N

get NodeRecord info

-D, --list

get NodeDescriptions of CAs only

-S

get ServiceRecord info

-I

get InformInfoRecord (subscription) info

-L

return the Lids of the name specified

-l

return the unique Lid of the name specified

-G

return the Guids of the name specified

-O

return the name for the Lid specified

-U

return the name for the Guid specified

-c

get the SA's class port info

-s

return the PortInfoRecords with isSM or isSMdisabled capability mask bit on

-g

get multicast group info

-m

get multicast member info. If a group is specified, limit the output to the group specified and print one line containing only the GUID and node description for each entry. Example: saquery -m 0xc000

-x

get LinkRecord info

--src-to-dst <src:dst>

get a PathRecord for <src:dst> where src and dst are either node names or LIDs

--sgid-to-dgid <sgid:dgid>

get a PathRecord for sgid to dgid where both GIDs are in an IPv6 format acceptable to inet_pton (3)

--smkey <val>

use SM_Key value for the query. Will be used only with "trusted" queries. If non-numeric value (like 'x') is specified then saquery will prompt for a value. Default (when not specified here or in /etc/infiniband-diags/ibdiag.conf) is to use SM_Key == 0 (or "untrusted")

-K, --show_keys

show security keys (mkey, smkey, etc.) associated with the request.

--slid <lid> Source LID (PathRecord)

--dlid <lid> Destination LID (PathRecord)

--mlid <lid> Multicast LID (MCMemberRecord)

--sgid <gid> Source GID (IPv6 format) (PathRecord)

--dgid <gid> Destination GID (IPv6 format) (PathRecord)

--gid <gid> Port GID (MCMemberRecord)

--mgid <gid> Multicast GID (MCMemberRecord)

--reversible Reversible path (PathRecord)

--numb_path Number of paths (PathRecord)

--pkey P_Key (PathRecord, MCMemberRecord). If non-numeric value (like 'x')

is specified then saquery will prompt for a value

--qos_class QoS Class (PathRecord)

--sl Service level (PathRecord, MCMemberRecord)

--mtu MTU and selector (PathRecord, MCMemberRecord)

--rate Rate and selector (PathRecord, MCMemberRecord)

--pkt_lifetime Packet lifetime and selector (PathRecord, MCMemberRecord)

--qkey Q_Key (MCMemberRecord). If non-numeric value (like 'x') is specified

then saquery will prompt for a value

--tclass Traffic Class (PathRecord, MCMemberRecord)

--flow_label Flow Label (PathRecord, MCMemberRecord)

--hop_limit Hop limit (PathRecord, MCMemberRecord)

--scope Scope (MCMemberRecord)

--join_state Join state (MCMemberRecord)

--proxy_join Proxy join (MCMemberRecord)

--service_id ServiceID (PathRecord)

Supported query names (and aliases):

```
ClassPortInfo (CPI)
NodeRecord (NR) [lid]
PortInfoRecord (PIR) [[lid]/[port]/[options]]
SL2VLTableRecord (SL2VL) [[lid]/[in_port]/[out_port]]
PKeyTableRecord (PKTR) [[lid]/[port]/[block]]
VLArbitrationTableRecord (VLAR) [[lid]/[port]/[block]]
InformInfoRecord (IIR)
LinkRecord (LR) [[from_lid]/[from_port]] [[to_lid]/[to_port]]
ServiceRecord (SR)
PathRecord (PR)
MCMemberRecord (MCMR)
LFTRecord (LFTR) [[lid]/[block]]
MFTRecord (MFTR) [[mlid]/[position]/[block]]
GUIDInfoRecord (GIR) [[lid]/[block]]
SwitchInfoRecord (SWIR) [lid]
SMInfoRecord (SMIR) [lid]
```

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

--outstanding_smps, -o <val>

Specify the number of outstanding SMP's which should be issued during the scan Default: 2

--node-name-map <node-name-map> Specify a node name map.

This file maps GUIDs to more user friendly names. See FILES section.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## COMMON FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

### NODE NAME MAP FILE FORMAT
The node name map is used to specify user friendly names for nodes in the output. GUIDs are used to perform the lookup.

This functionality is provided by the opensm-libs package. See opensm(8) for the file location for your installation.

Generically:

```
# comment
<guid> "<name>"
```

Example:

```
# IB1
# Line cards
0x0008f104003f125c "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f125d "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d2 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d3 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10bf "IB1 (Rack 11 slot 12  ) ISR9288/ISR9096 Voltaire sLB-24D"
# Spines
0x0008f10400400e2d "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2e "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2f "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e31 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e32 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
# GUID   Node Name
0x0008f10400411a08 "SW1  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a28 "SW2  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a34 "SW3  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f104004119d0 "SW4  (Rack  3) ISR9024 Voltaire 9024D"
```

## DEPENDENCIES
OpenSM (or other running SM/SA), libosmcomp, libibumad, libibmad

## AUTHORS
Ira Weiny

< ira.weiny@intel.com >

Hal Rosenstock

< halr@mellanox.com >


sminfo

title: sminfo(8)

summary: query InfiniBand SMInfo attribute

text:
# sminfo(8)

## NAME
sminfo - query InfiniBand SMInfo attribute

## SYNOPSIS
sminfo [options] sm_lid | sm_dr_path [modifier]

## DESCRIPTION
Optionally set and display the output of a sminfo query in human readable format. The target SM is the one listed in the local port info, or the SM specified by the optional SM lid or by the SM direct routed path.

Note: using sminfo for any purposes other then simple query may be very dangerous, and may result in a malfunction of the target SM.

## OPTIONS
-s, --state <state> set SM state

0 not active 1 discovering

2 standby

3 master

-p, --priority <priority> set priority (0-15)

-a, --activity <val> set activity count

### Addressing Flags
-D, --Direct The address specified is a directed route

```
Examples:

   [options] -D [options] "0"          # self port

   [options] -D [options] "0,1,2,1,4"  # out via port 1, then 2, ...

   (Note the second number in the path specified must match the port being

   used.  This can be specified using the port selection flag '-P' or the

   port found through the automatic selection process.)
```

-G, --Guid The address specified is a Port GUID

-L, --Lid The address specified is a LID

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

-y, --m_key <key>

use the specified M_key for requests. If non-numeric value (like 'x') is specified then a value will be prompted for.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

## EXAMPLES
::

sminfo # local port's sminfo sminfo 32 # show sminfo of lid 32 sminfo -G 0x8f1040023 # same but using guid address

## SEE ALSO
smpdump (8)

## AUTHOR
Hal Rosenstock

< halr@voltaire.com >


smpdump

title: smpdump(8)

text:
# smpdump(8)

## NAME
smpdump - dump InfiniBand subnet management attributes

## SYNOPSIS
smpdump [options] <dlid|dr_path> <attribute> [attribute_modifier]

## DESCRIPTION
smpdump is a general purpose SMP utility which gets SM attributes from a specified SMA. The result is dumped in hex by default.

## OPTIONS
dlid|drpath

LID or DR path to SMA

attribute

IBA attribute ID for SM attribute

attribute_modifier

IBA modifier for SM attribute

-s, --string

Print strings in packet if possible

### Addressing Flags
-D, --Direct The address specified is a directed route

```
Examples:

   [options] -D [options] "0"          # self port

   [options] -D [options] "0,1,2,1,4"  # out via port 1, then 2, ...

   (Note the second number in the path specified must match the port being

   used.  This can be specified using the port selection flag '-P' or the

   port found through the automatic selection process.)
```

-L, --Lid The address specified is a LID

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

## EXAMPLES
Direct Routed Examples

::

smpdump -D 0,1,2,3,5 16 # NODE DESC smpdump -D 0,1,2 0x15 2 # PORT INFO, port 2

LID Routed Examples

::

smpdump 3 0x15 2 # PORT INFO, lid 3 port 2 smpdump 0xa0 0x11 # NODE INFO, lid 0xa0

## SEE ALSO
smpquery (8)

## AUTHOR
Hal Rosenstock

< halr@voltaire.com >


smpquery

title: smpquery(8)

text:
# smpquery(8)

## NAME
smpquery - query InfiniBand subnet management attributes

## SYNOPSIS
smpquery [options] <op> <dest dr_path|lid|guid> [op params]

## DESCRIPTION
smpquery allows a basic subset of standard SMP queries including the following: node info, node description, switch info, port info. Fields are displayed in human readable format.

## OPTIONS
Current supported operations (case insensitive) and their parameters:

```
Nodeinfo (NI) <addr>
Nodedesc (ND) <addr>
Portinfo (PI) <addr> [<portnum>]     # default port is zero
PortInfoExtended (PIE) <addr> [<portnum>]
Switchinfo (SI) <addr>
PKeyTable (PKeys) <addr> [<portnum>]
SL2VLTable (SL2VL) <addr> [<portnum>]
VLArbitration (VLArb) <addr> [<portnum>]
GUIDInfo (GI) <addr>
MlnxExtPortInfo (MEPI) <addr> [<portnum>]  # default port is zero
```

-c, --combined

Use Combined route address argument <lid> <DR_Path>

-x, --extended

Set SMSupportsExtendedSpeeds bit 31 in AttributeModifier (only impacts PortInfo queries).

-K, --show_keys

show security keys (mkey, smkey, etc.) associated with the request.

### Addressing Flags
-D, --Direct The address specified is a directed route

```
Examples:

   [options] -D [options] "0"          # self port

   [options] -D [options] "0,1,2,1,4"  # out via port 1, then 2, ...

   (Note the second number in the path specified must match the port being

   used.  This can be specified using the port selection flag '-P' or the

   port found through the automatic selection process.)
```

-G, --Guid The address specified is a Port GUID

-L, --Lid The address specified is a LID

-s, --sm_port <smlid> use 'smlid' as the target lid for SA queries.

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

--node-name-map <node-name-map> Specify a node name map.

This file maps GUIDs to more user friendly names. See FILES section.

-y, --m_key <key>

use the specified M_key for requests. If non-numeric value (like 'x') is specified then a value will be prompted for.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

### NODE NAME MAP FILE FORMAT
The node name map is used to specify user friendly names for nodes in the output. GUIDs are used to perform the lookup.

This functionality is provided by the opensm-libs package. See opensm(8) for the file location for your installation.

Generically:

```
# comment
<guid> "<name>"
```

Example:

```
# IB1
# Line cards
0x0008f104003f125c "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f125d "IB1 (Rack 11 slot 1   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d2 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10d3 "IB1 (Rack 11 slot 2   ) ISR9288/ISR9096 Voltaire sLB-24D"
0x0008f104003f10bf "IB1 (Rack 11 slot 12  ) ISR9288/ISR9096 Voltaire sLB-24D"
# Spines
0x0008f10400400e2d "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2e "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e2f "IB1 (Rack 11 spine 1   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e31 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
0x0008f10400400e32 "IB1 (Rack 11 spine 2   ) ISR9288 Voltaire sFB-12D"
# GUID   Node Name
0x0008f10400411a08 "SW1  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a28 "SW2  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f10400411a34 "SW3  (Rack  3) ISR9024 Voltaire 9024D"
0x0008f104004119d0 "SW4  (Rack  3) ISR9024 Voltaire 9024D"
```

## EXAMPLES
::

smpquery portinfo 3 1 # portinfo by lid, with port modifier smpquery -G switchinfo 0x2C9000100D051 1 # switchinfo by guid smpquery -D nodeinfo 0 # nodeinfo by direct route smpquery -c nodeinfo 6 0,12 # nodeinfo by combined route

## SEE ALSO
smpdump (8)

## AUTHOR
Hal Rosenstock

< hal@mellanox.com >


vendstat

title: vendstat(8)

text:
# vendstat(8)

## NAME
vendstat - query InfiniBand vendor specific functions

## SYNOPSIS
vendstat [options] <lid|guid>

## DESCRIPTION
vendstat uses vendor specific MADs to access beyond the IB spec vendor specific functionality. Currently, there is support for Mellanox InfiniSwitch-III (IS3) and InfiniSwitch-IV (IS4).

## OPTIONS
-N

show IS3 or IS4 general information.

-w

show IS3 port xmit wait counters.

-i

show IS4 counter group info.

-c <num,num>

configure IS4 counter groups. Configure IS4 counter groups 0 and 1. Such configuration is not persistent across IS4 reboot. First number is for counter group 0 and second is for counter group 1.

Group 0 counter config values:

::

0 - PortXmitDataSL0-7 1 - PortXmitDataSL8-15 2 - PortRcvDataSL0-7

Group 1 counter config values:

::

1 - PortXmitDataSL8-15 2 - PortRcvDataSL0-7 8 - PortRcvDataSL8-15

-R, --Read <addr,mask>

Read configuration space record at addr

-W, --Write <addr,val,mask>

Write configuration space record at addr

### Addressing Flags
-G, --Guid The address specified is a Port GUID

-L, --Lid The address specified is a LID

-s, --sm_port <smlid> use 'smlid' as the target lid for SA queries.

### Port Selection flags
-C, --Ca <ca_name> use the specified ca_name.

-P, --Port <ca_port> use the specified ca_port.

### Local port Selection
Multiple port/Multiple CA support: when no IB device or port is specified (see the "local umad parameters" below), the libibumad library selects the port to use by the following criteria:

1.

the first port that is ACTIVE.

2.

if not found, the first port that is UP (physical link up).

If a port and/or CA name is specified, the libibumad library attempts to fulfill the user request, and will fail if it is not possible.

For example:

```
ibaddr                 # use the first port (criteria #1 above)
ibaddr -C mthca1       # pick the best port from "mthca1" only.
ibaddr -P 2            # use the second (active/up) port from the first available IB device.
ibaddr -C mthca0 -P 2  # use the specified port only.
```

### Debugging flags
-d

raise the IB debugging level. May be used several times (-ddd or -d -d -d).

-e

show send and receive errors (timeouts and others)

-h, --help show the usage message

-v, --verbose

increase the application verbosity level. May be used several times (-vv or -v -v -v)

-V, --version show the version info.

### Configuration flags
-t, --timeout <timeout_ms> override the default timeout for the solicited mads.

--config, -z <config_file> Specify alternate config file.

Default: /etc/infiniband-diags/ibdiag.conf

## FILES

### CONFIG FILE
/etc/infiniband-diags/ibdiag.conf

A global config file is provided to set some of the common options for all tools. See supplied config file for details.

## EXAMPLES
::

vendstat -N 6 # read IS3 or IS4 general information vendstat -w 6 # read IS3 port xmit wait counters vendstat -i 6 12 # read IS4 port 12 counter group info vendstat -c 0,1 6 12 # configure IS4 port 12 counter groups for PortXmitDataSL vendstat -c 2,8 6 12 # configure IS4 port 12 counter groups for PortRcvDataSL

## AUTHOR
Hal Rosenstock

< hal.rosenstock@gmail.com >


ibcheckerrors

package: infiniband-diags-compat

title: ibcheckerrors(8)

summary: validate IB subnet and report errors

text:
# ibcheckerrors(8)

## NAME
ibcheckerrors - validate IB subnet and report errors

## SYNOPSIS
ibcheckerrors [-h] [-b] [-v] [-N | -nocolor] [<topology-file> | -C ca_name -P ca_port -t(imeout) timeout_ms]

## DESCRIPTION
ibcheckerrors is a script which uses a full topology file that was created by ibnetdiscover, scans the network to validate the connectivity and reports errors (from port counters).

## OPTIONS
-v increase the verbosity level

-b brief mode. Reduce the output to show only if errors are present,

not what they are.

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## SEE ALSO
ibnetdiscover(8), ibchecknode(8), ibcheckport(8), ibcheckerrs(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckerrs

title: ibcheckerrs(8)

text:
# ibcheckerrs(8)

## NAME
ibcheckerrs - validate IB port (or node) and report errors in counters above threshold

## SYNOPSIS
ibcheckerrs [-h] [-b] [-v] [-G] [-T <threshold_file>] [-s(how_thresholds)] [-N | -nocolor] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid> <port>

## DESCRIPTION
Check specified port (or node) and report errors that surpassed their predefined threshold. Port address is lid unless -G option is used to specify a GUID address. The predefined thresholds can be dumped using the -s option, and a user defined threshold_file (using the same format as the dump) can be specified using the -t <file> option.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-s show predefined thresholds

-T use specified threshold file

-v increase the verbosity level

-b brief mode. Reduce the output to show only if errors are

present, not what they are.

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibcheckerrs 2 # check aggregated node counter for lid 2

ibcheckerrs 2 4 # check port counters for lid 2 port 4

ibcheckerrs -T xxx 2 # check node using xxx threshold file

## SEE ALSO
perfquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibchecknet

title: ibchecknet(8)

summary: validate IB subnet and report errors

text:
# ibchecknet(8)

## NAME
ibchecknet - validate IB subnet and report errors

## SYNOPSIS
ibchecknet [-h] [-N | -nocolor] [<topology-file> | -C ca_name -P ca_port -t(imeout) timeout_ms]

## DESCRIPTION
ibchecknet is a script which uses a full topology file that was created by ibnetdiscover, and scans the network to validate the connectivity and reports errors (from port counters).

## OPTIONS
-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## SEE ALSO
ibnetdiscover(8), ibchecknode(8), ibcheckport(8), ibcheckerrs(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibchecknode

title: ibchecknode(8)

summary: validate IB node and report errors

text:
# ibchecknode(8)

## NAME
ibchecknode - validate IB node and report errors

## SYNOPSIS
ibchecknode [-h] [-v] [-N | -nocolor] [-G] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid>

## DESCRIPTION
Check connectivity and do some simple sanity checks for the specified node. Port address is a lid unless -G option is used to specify a GUID address.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-v increase the verbosity level

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibchecknode 2 # check node via lid 2

## SEE ALSO
smpquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckport

title: ibcheckport(8)

summary: validate IB port and report errors

text:
# ibcheckport(8)

## NAME
ibcheckport - validate IB port and report errors

## SYNOPSIS
ibcheckport [-h] [-v] [-N | -nocolor] [-G] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid> <port>

## DESCRIPTION
Check connectivity and do some simple sanity checks for the specified port. Port address is a lid unless -G option is used to specify a GUID address.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-v increase the verbosity level

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibcheckport 2 3 # check lid 2 port 3

## SEE ALSO
smpquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckportstate

title: ibcheckportstate(8)

text:
# ibcheckportstate(8)

## NAME
ibcheckportstate - validate IB port for LinkUp and not Active state

## SYNOPSIS
ibcheckportstate [-h] [-v] [-N | -nocolor] [-G] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid> <port>

## DESCRIPTION
Check connectivity and check the specified port for proper port state (Active) and port physical state (LinkUp). Port address is a lid unless -G option is used to specify a GUID address.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-v increase the verbosity level

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibcheckportstate 2 3 # check lid 2 port 3

## SEE ALSO
smpquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckportwidth

title: ibcheckportwidth(8)

summary: validate IB port for 1x link width

text:
# ibcheckportwidth(8)

## NAME
ibcheckportwidth - validate IB port for 1x link width

## SYNOPSIS
ibcheckportwidth [-h] [-v] [-N | -nocolor] [-G] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid> <port>

## DESCRIPTION
Check connectivity and check the specified port for 1x link width. Port address is a lid unless -G option is used to specify a GUID address.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-v increase the verbosity level

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibcheckportwidth 2 3 # check lid 2 port 3

## SEE ALSO
smpquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckstate

title: ibcheckstate(8)

text:
# ibcheckstate(8)

## NAME
ibcheckstate - find ports in IB subnet which are link up but not active

## SYNOPSIS
ibcheckstate [-h] [-v] [-N | -nocolor] [<topology-file> | -C ca_name -P ca_port -t(imeout) timeout_ms]

## DESCRIPTION
ibcheckstat is a script which uses a full topology file that was created by ibnetdiscover, scans the network to validate the port state and port physical state, and reports any ports which have a port state other than Active or a port physical state other than LinkUp.

## OPTIONS
-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## SEE ALSO
ibnetdiscover(8), ibchecknode(8), ibcheckportstate(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibcheckwidth

title: ibcheckwidth(8)

summary: find 1x links in IB subnet

text:
# ibcheckwidth(8)

## NAME
ibcheckwidth - find 1x links in IB subnet

## SYNOPSIS
ibcheckwidth [-h] [-v] [-N | -nocolor] [<topology-file> | -C ca_name -P ca_port -t(imeout) timeout_ms]

## DESCRIPTION
ibcheckwidth is a script which uses a full topology file that was created by ibnetdiscover, scans the network to validate the active link widths and reports any 1x links.

## OPTIONS
-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## SEE ALSO
ibnetdiscover(8), ibchecknode(8), ibcheckportwidth(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibdatacounters

title: ibdatacounters(8)

summary: query IB subnet for data counters

text:
# ibdatacounters(8)

## NAME
ibdatacounters - query IB subnet for data counters

## SYNOPSIS
ibdatacounters [-h] [-b] [-v] [-N | -nocolor] [<topology-file> | -C ca_name -P ca_port -t(imeout) timeout_ms]

## DESCRIPTION
ibdatacounters is a script which uses a full topology file that was created by ibnetdiscover, scans the network to validate the connectivity and reports the data counters (from port counters).

## OPTIONS
-v increase the verbosity level

-b brief mode. Reduce the output to show only if errors are present,

not what they are.

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## SEE ALSO
ibnetdiscover(8), ibdatacounts(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibdatacounts

title: ibdatacounts(8)

summary: get IB port data counters

text:
# ibdatacounts(8)

## NAME
ibdatacounts - get IB port data counters

## SYNOPSIS
ibdatacounts [-h] [-b] [-v] [-G] [-N | -nocolor] [-C ca_name] [-P ca_port] [-t(imeout) timeout_ms] <lid|guid> [<port>]

## DESCRIPTION
Obtain PMA data counters from specified port (or node). Port address is lid unless -G option is used to specify a GUID address.

## OPTIONS
-G use GUID address argument. In most cases, it is the Port GUID.

Example:

"0x08f1040023"

-v increase the verbosity level

-b brief mode

-N | -nocolor use mono rather than color mode

-C <ca_name> use the specified ca_name.

-P <ca_port> use the specified ca_port.

-t <timeout_ms> override the default timeout for the solicited mads.

## EXAMPLE
ibdatacounts 2 # show data counters for lid 2

ibdatacounts 2 4 # show data counters for lid 2 port 4

## SEE ALSO
perfquery(8), ibaddr(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibdiscover

title: ibdiscover(8)

text:
# ibdiscover(8)

## NAME
ibdiscover.pl - annotate and compare InfiniBand topology

## SYNOPSIS
ibdiscover.pl

## DESCRIPTION
ibdiscover.pl uses a topology file create by ibnetdiscover and a discover.map file which the network administrator creates which indicates the nodes to be expected and a ibdiscover.topo file which is the expected connectivity and produces a new connectivity file (discover.topo.new) and outputs the changes to stdout. The network administrator can choose to replace the "old" topo file with the new one or certain changes in.

The syntax of the ibdiscover.map file is:

<nodeGUID>|port|"Text for node"|<NodeDescription from ibnetdiscover format>

e.g.

8f10400410015|8|"ISR 6000"|# SW-6IB4 Voltaire port 0 lid 5

8f10403960558|2|"HCA 1"|# MT23108 InfiniHost Mellanox Technologies

The syntax of the old and new topo files (ibdiscover.topo and ibdiscover.topo.new) are:

<LocalPort>|<LocalNodeGUID>|<RemotePort>|<RemoteNodeGUID>

e.g.

10|5442ba00003080|1|8f10400410015

These topo files are produced by the ibdiscover.pl tool.

## USAGE
ibnetdiscover | ibdiscover.pl

## SEE ALSO
ibnetdiscover(8)

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibprintca

title: ibprintca(8)

text:
# ibprintca(8)

## NAME
ibprintca.pl - print either the ca specified or the list of cas from the ibnetdiscover output

## SYNOPSIS
ibprintca.pl [-R -l -C <ca_name> -P <ca_port>] [<ca_guid|node_name>]

## DESCRIPTION
Faster than greping/viewing with an editor the output of ibnetdiscover, ibprintca.pl will parse out and print either the CA information for the specified CA or a list of all the CAs in the subnet.

Finally, ibprintca.pl will also reuse the cached ibnetdiscover output from some of the other diag tools which makes it a bit faster than running ibnetdiscover from scratch.

## OPTIONS
-l

List the CAs (simply a wrapper for ibhosts).

-R

Recalculate the ibnetdiscover information, ie do not use the cached information. This option is slower but should be used if the diag tools have not been used for some time or if there are other reasons to believe that the fabric has changed.

-C <ca_name> use the specified ca_name for the search.

-P <ca_port> use the specified ca_port for the search.

## AUTHORS
Ira Weiny

<weiny2@llnl.gov>

Hal Rosenstock

<halr@voltaire.com>


ibprintrt

title: ibprintrt(8)

text:
# ibprintrt(8)

## NAME
ibprintrt.pl - print either only the router specified or a list of routers from the ibnetdiscover output

## SYNOPSIS
ibprintrt.pl [-R -l -C <ca_name> -P <ca_port>] [<rt_guid|node_name>]

## DESCRIPTION
Faster than greping/viewing with an editor the output of ibnetdiscover, ibprintrt.pl will parse out and print either the router information for the specified IB router or a list of all IB routers in the subnet.

Finally, ibprintrt.pl will also reuse the cached ibnetdiscover output from some of the other diag tools which makes it a bit faster than running ibnetdiscover from scratch.

## OPTIONS
-l

List the Rts (simply a wrapper for ibrouters).

-R

Recalculate the ibnetdiscover information, ie do not use the cached information. This option is slower but should be used if the diag tools have not been used for some time or if there are other reasons to believe that the fabric has changed.

-C <ca_name> use the specified ca_name for the search.

-P <ca_port> use the specified ca_port for the search.

## AUTHOR
Hal Rosenstock

<halr@voltaire.com>


ibprintswitch

title: ibprintswitch(8)

text:
# ibprintswitch(8)

## NAME
ibprintswitch.pl - print either the switch specified or a list of switches from the ibnetdiscover output

## SYNOPSIS
ibprintswitch.pl [-R -l -C <ca_name> -P <ca_port>] [<switch_guid|switch_name>]

## DESCRIPTION
Faster than greping/viewing with an editor the output of ibnetdiscover, ibprintswitch.pl will parse out and print either the switch information for the switch specified or a list of all the switches found in the subnet. In addition, it will crudely parse on the node description information and if found report all the information for an entire chasis if the description information is consistent.

Finally, ibprintswitch.pl will also reuse the cached ibnetdiscover output from some of the other diag tools which makes it a bit faster than running ibnetdiscover from scratch.

## OPTIONS
-l

List the switches (simply a wrapper for ibswitches).

-R

Recalculate the ibnetdiscover information, ie do not use the cached information. This option is slower but should be used if the diag tools have not been used for some time or if there are other reasons to believe that the fabric has changed.

-C <ca_name> use the specified ca_name for the search.

-P <ca_port> use the specified ca_port for the search.

## AUTHORS
Ira Weiny

<weiny2@llnl.gov>

Hal Rosenstock

<halr@voltaire.com>


ibswportwatch

title: ibswportwatch(8)

text:
# ibswportwatch(8)

## NAME
ibswportwatch.pl - poll the counters on the specified switch/port and report rate of change information.

## SYNOPSIS
ibswportwatch.pl [-p <pause_time> -v -n <cycles> -G] <guid|lid> <port>

## DESCRIPTION
ibswportwatch.pl polls the port counters of the specified port and calculates rate of change information.

## OPTIONS
-p <pause_time>

Specify a pause time (polling interval) other than the default.

-v

Be verbose.

-n <cycles>

Run for a set number of poll intervals and stop. (Default == -1 == forever)

-G

The address provided is a GUID rather than LID.

## AUTHOR
Ira Weiny

<weiny2@llnl.gov>


update-info-dir

package: info-install

title: update-info-dir(8)

text:
# update-info-dir(8)

## NAME
update-info-dir - (re-)create /usr/share/info/dir from all installed info files

## SYNOPSIS
update-info-dir [options]

## DESCRIPTION
This manual page documents briefly the update-info-dir command. This manual page was written for the Debian GNU/Linux distribution because the original script was designed for Debian packaging system.

update-info-dir [info-directory] (re-)creates the index of available documentation in info format (the file /usr/share/info/dir) which is usually presented by info browsers on startup.

## OPTIONS
info-directory

If an argument is given update the dir file in the directory given, otherwise use /usr/share/info.

## AUTHOR
This manual page was written by Norbert Preining <preining@logic.at>, for the Debian GNU/Linux system (but may be used by others).


actsync

package: inn

title: actsync(8)

summary: Synchronize newsgroups

text:
# actsync(8)

## NAME
actsync, actsyncd - Synchronize newsgroups

## SYNOPSIS
actsync [-AkmT] [-b hostid] [-d hostid] [-g max] [-i ignore-file] [-I hostid] [-l hostid] [-n name] [-o format] [-p min-unchanged] [-q hostid] [-s size] [-t hostid] [-v verbosity] [-w seconds] [-z seconds] [host] host

actsyncd config [debug-level [debug-format]]

## DESCRIPTION
actsync permits one to synchronize, compare, or merge two active files. With this utility one may add, change, or remove newsgroups on the local news server to make it similar to the list of the newsgroups found on another system or file. The synchronization need not be exact. Local differences in newsgroup lists may be maintained and preserved. Certain newsgroup errors may be detected and optionally corrected.

There are several reasons to run actsync (or actsyncd) on a periodic basis. Among the reasons are:

- A control message to add, change or remove a newsgroup may fail to reach your site.

- Your control.ctl may be out of date or incomplete.

- News articles for a new newsgroup may arrive ahead (sometimes days ahead) of the control message.

- Control messages may be forged, thus bypassing the restrictions found in control.ctl unless you set up PGP authentication (and even then, not all hierarchies use PGP authentication).

- Your active file may have been trashed.

If either host argument begins with "." or "/", it is assumed to be the name of a file containing information in the active(5) format. The getlist(1) utility may be used to obtain a copy of a remote system's active file via its NNTP server, or an FTP client program can retrieve such a file from an FTP archive (such as ftp.isc.org available in both FTP and HTTPS <https://ftp.isc.org/pub/usenet/CONFIG/active>; see more about this below). Newsgroup information from a file may be treated as if it was obtained from a host. In this man page, the host arguments on the command line are called hosts, even though they may be file names.

If a host argument does not begin with "." or "/", it is assumed to be a hostname or Internet address. In this case, actsync will attempt to use the NNTP protocol to obtain a copy of the specified system's active file. If the host argument contains ":", the right side will be considered the port to connect to on the remote system. If no port number is specified, actsync will connect to port 119.

Regardless how the active file information is obtained, the actions of actsync remain the same.

The first host specified is taken to be the local host, the one where any changes would be made. The second host specified is the remote host that is being synchronized with. If only one host is specified, it is assumed to be the remote host to synchronize with, and the local host is assumed to be the default local NNTP server as specified by the NNTPSERVER environment variable or by the server value found in inn.conf.

If either host is specified as "-", the default server will be used for that host, determined as described above.

The newsgroup synchronization, by default, involves all newsgroups found on both hosts. One may also synchronize a subset of newsgroups by directing actsync to ignore certain newsgroups from both systems. Only newsgroups with valid names will be synchronized. To be valid, a newsgroup name must consist only of alphanumeric characters, ".", "+", "-", and "_". One may not have two "." characters in a row. The first character must be alphanumeric, as must any character following ".". The name may not end in a "." character.

The actsyncd daemon provides a convenient interface to configure and run actsync. If a host is not initially reachable, the daemon will retry up to 9 additional times, waiting 6 minutes before each retry. This daemon runs in the foreground, sending output to standard output and standard error. It then uses mod-active(8) to update the active file if there are commands for ctlinnd in its output.

The configuration filename for the daemon is given as a command line argument, usually actsync.cfg in pathetc. The config file can contain the following options:

```
    host=<host>
    ftppath=<path-to-active>
    ignore_file=<ignore-file>
    flags=<actsync-options>
```

The host=, ignore_file=, and flags= lines are mandatory. Each keyword must start at the beginning of the line, and there may be no whitespace before the "=" character. Blank lines are ignored, as are comment lines that start with "#". Any other lines may produce undefined results.

The <host> setting refers to the second (remote) host parameter to actsync. If <path-to-active> is provided, <host> is accessed as an FTP server, retrieving the file named. If the filename ends in ".gz" or ".Z", it will be automatically uncompressed after retrieval. <ignore-file> names the ignore file used by actsync (the -i option). <actsync-options> contains any other flags that you wish to pass to actsync.

Note that one should not include -i or -o options in the flags= line; they are automatically taken care of by actsyncd.

One may produce a trial actsyncd run without changing anything on the server by supplying the debug-level argument:

```
    actsyncd <pathetc>/actsync.cfg 2
```

The debug-level causes actsyncd to run actsync with a -v debug-level flag (overriding any -v flag on the flags= line), not make any changes to the active file, write a new active file to standard output, and write debug messages to standard error.

If the debug-format argument is also given to actsyncd, the data written to standard output will be in -o debug-format instead of in "-o a1" format.

INN comes with default values of "ftp.isc.org" for <host> and "/pub/usenet/CONFIG/active.gz" for <path-to-active>. You can read about the policies used for maintaining that active file at <https://ftp.isc.org/pub/usenet/CONFIG/README>. Consider synchronizing from this file on a daily basis by using cron.

## OPTIONS
actsync takes the following options.

In all of the following options, the hostid parameter takes one of the following values:

```
    0    neither server
    1    local default server
    2    remote server
    12   both servers
    21   both servers
```

In other words, 1 refers to the local host (the first host argument on the actsync command line) and 2 refers to the remote host (the second host argument, or the only one if only one is given).

-A

actsync tries to authenticate before issuing the LIST command.

-b hostid

This flag causes actsync to ignore for synchronization purposes newsgroups with "bork.bork.bork"-style names (newsgroups whose last 3 components are identical). For example, the following newsgroups have bork-style names:

```
    alt.helms.dork.dork.dork
    alt.auto.accident.sue.sue.sue
    alt.election.vote.vote.vote

```

The default is "-b 0"; no newsgroups are ignored because of bork-style names.

-d hostid

This flag causes actsync to ignore newsgroups that have all numeric path components. For example, the following newsgroups have numeric path components:

```
    alt.prime.chongo.23209
    391581.times.2.to_the.216193.power.-1
    99.bottles.of.treacle.on.the.wall
    linfield.class.envio_bio.101.d

```

The newsgroups directory of a newsgroup with a all numeric component could conflict with an article from another group if stored using the tradspool storage method; see storage.conf(5). For example, the directory for the first newsgroup listed above is the same path as article number 23209 from the newsgroup:

```
    alt.prime.chongo

```

The default is "-d 0"; all numeric newsgroups from both hosts will be processed.

-g max

Ignore any newsgroup with more than max levels. For example, "-g 6" would ignore:

```
    alt.feinstien.votes.to.trash.freedom.of.speech
    alt.senator.exon.enemy.of.the.internet
    alt.crypto.export.laws.dumb.dumb.dumb

```

but would not ignore:

```
    alt.feinstien.acts.like.a.republican
    alt.exon.amendment
    alt.crypto.export.laws

```

If max is 0, then the max level feature is disabled.

By default, the max level feature is disabled.

-i ignore-file

The ignore-file, usually actsync.ign in pathetc, allows one to have a fine degree of control over which newsgroups are ignored. It contains a set of rules that specifies which newsgroups will be checked and which will be ignored. By default, these rules apply to both hosts. This can be modified by using the -I flag.

Blank lines and text after a "#" are considered comments and are ignored.

Rule lines consist of tokens separated by whitespace. Rule lines may be one of two forms:

```
    c <newsgroup> [<type> ...]
    i <newsgroup> [<type> ...]

```

If the rule begins with a "c", the rule requests certain newsgroups to be checked. If the rule begins with an "i", the rule requests certain newsgroups to be ignored. The <newsgroup> field may be a specific newsgroup, or a uwildmat(3) pattern.

If one or more <type>s are specified, then the rule applies to the newsgroup only if it is of the specified type. Types refer to the 4th field of the active file; that is, a type may be one of:

```
    y
    n
    m
    j
    x
    =group.name

```

Unlike active files, the "group.name" in an alias type may be a newsgroup name or a uwildmat(3) pattern. Also, "=" is equivalent to "=*".

On each rule line, no pattern type may be repeated. For example, one may not have more than one type that begins with "=", per line. However, one may achieve an effect equivalent to using multiple "=" types by using multiple rule lines affecting the same newsgroup.

By default, all newsgroups are candidates to be checked. If no ignore-file is specified, or if the ignore file contains no rule lines, all newsgroups will be checked. If an ignore file is used, each newsgroup in turn is checked against the ignore file. If multiple lines match a given newsgroup, the last line in the ignore file is used.

For example, consider the following ignore file lines:

```
    i *.general
    c *.general m
    i nsa.general

```

The newsgroups ba.general and mod.general would be synchronized if moderated and ignored if not moderated. The newsgroup nsa.general would be ignored regardless of moderation status. All newsgroups not matching *.general would be synchronized by default.

-I hostid

This flag restricts which hosts are affected by the ignore file. This flag may be useful in conjunction with the -m flag. For example:

```
    actsync -i actsync.ign -I 2 -m host1 host2

```

will keep all newsgroups currently on host1. It will also only compare host1 groups with non-ignored newsgroups from host2.

The default is "-I 12"; newsgroups from both hosts are ignored per the file specified with -i.

-k

By default, any newsgroup on the local host that has an invalid name will be considered for removal. This causes actsync simply ignore such newsgroups. This flag, used in combination with -m, will prevent any newsgroup from being scheduled for removal.

-l hostid

This flag causes problem newsgroups of type "=" to be considered as errors. Newsgroups of type "=" are newsgroups active entries that have a fourth field that begins with "="; i.e., newsgroups that are aliased to other newsgroups. A problem newsgroup is one for which one of the following is true:

- Aliased to itself.

- In an alias chain that loops around to itself.

- In an alias chain longer than 16 groups.

- Aliased to a non-existant newsgroup.

- Aliased to a newsgroup that has an error of some kind.

However, a newsgroup that is equivalent to an ignored newsgroup is not a problem.

The default is "-l 12": problem newsgroups from both hosts are marked as errors.

-m

Merge newsgroups instead of sync. By default, if a newsgroup exists on the local host but not the remote, it will be scheduled to be removed. This flag disables this process, permitting newsgroups unique to the local host to be kept.

-n name

Depending on -o, the ctlinnd(8) command may be used to create newsgroups as necessary. When this is done, the default creator name used is "actsync". This flag changes the creator name to name.

-o format

Determine the output or action format of this utility. format may be one of:

a

Output in active(5) format.

a1

Output in active(5) format and output non-error ignored groups from the local host.

ak

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for any newsgroup being created.

aK

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for all newsgroups found on that host.

a1k

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for any newsgroup being created and output non-error ignored groups from the local host.

a1K

Output in active(5) format, but use the high and low (2nd and 3rd active fields) values from the remote host for all newsgroups found on that host and output non-error ignored groups from the local host.

ak1

Same as "a1k".

aK1

Same as "a1K".

c

Output as commands to ctlinnd.

x

No output. Instead, directly run ctlinnd commands.

xi

No output. Instead, directly run ctlinnd commands in an interactive mode.

The "a", "a1", "ak", "aK", "a1k", "a1K", "ak1", and "aK1" style formats allow one to format new active file instead of producing ctlinnd commands. They use high and low values of 0000000000 and 0000000001 respectively for newsgroups that are created unless otherwise specified. The "ak" and "aK" variants change the high and low values (2nd and 3rd active fields). In the case of "ak", newsgroups created take their high and low values from the remote host. In the case of "aK", all newsgroups found on the remote host take their high and low values from it.

The "c" format produces ctlinnd commands. No actions are taken because actsync simply prints ctlinnd commands on standard output. This output format is useful to let you see how the local host will be affected by the sync (or merge) with the remote host.

The sync (or merge) may be accomplished directly by use of the "x" or "xi" format. With this format, actsync uses the execl(2) system call to directly execute ctlinnd commands. The output of such exec calls may be seen if the verbosity level is at least 2.

The actsync utility will pause for 4 seconds before each command is executed if "-o x" is selected. See the -z flag below for discussion of this delay and how to customize it.

The "xi" format interactively prompts on standard output and reads directives on standard input. One may pick and choose changes using this format.

Care should be taken when producing active(5) formatted output. One should check to be sure that actsync exited with a zero status prior to using such output. Also one should realize that such output will not contain lines ignored due to -i even if "-p 100" is used.

By default, "-o c" is assumed.

-p min-unchanged

By default, the actsync utility has safeguards against performing massive changes. If fewer than min-unchanged percent of the non-ignored lines from the local host remain unchanged, no actions (output, execution, etc.) are performed and actsync exits with a non-zero exit status. The min-unchanged value may be a floating point value such as 66.667. A change is a local newsgroup line that was removed, added, changed, or found to be in error. Changing the 2nd or 3rd active fields via "-o ak" or "-o aK" are not considered changes by -p.

To force actsync to accept any amount of change, use the "-p 0" option. To force actsync to reject any changes, use the "-p 100" option.

Care should be taken when producing active(5) formatted output. One should check to be sure that actsync exited with a zero status prior to using such output. Also one should realize that such output will not contain lines ignored due to -i even if "-p 100" is used.

By default, 96% of the lines not ignored in the first host argument on the actsync command line must be unchanged. That is, by default, "-p 96" is assumed.

-q hostid

By default, all newsgroup errors are reported on standard error. This flag quiets errors from the specified hostid.

-s size

If size is greater than 0, then ignore newsgroups with names longer than size and ignore newsgroups aliased (by following "=" chains) to names longer than size. Length checking is performed on both the local and remote hosts. By default, size is 0 and thus no length checking is performed.

-t hostid

Ignore improper newsgroups consisting of only a top component from the specified hostid. The following newsgroups are considered proper newsgroups despite top only names and therefore are exempt from this flag:

```
    control
    general
    junk
    test
    to

```

For example, the following newsgroup names are improper because they only contain a top level component:

```
    dole_for_pres
    dos
    microsoft
    windows95

```

The default is "-t 2"; that is, all improper top-level-only newsgroups from the remote host are ignored.

-T

This flag causes newsgroups on the remote host in new hierarchies to be ignored. Normally a newsgroup which only exists on the remote host, chongo.was.here for example, is created on the local host. However, if this flag is given and the local host does not have any other newsgroups in the same hierarchy (chongo.* in this case), the newsgroup in question will be ignored and will not be created on the local host.

-v verbosity

By default, actsync is not verbose. This flag controls the verbosity level as follows:

0

No debug or status reports (default).

1

Print summary, but only if work was needed or done.

2

Print actions, exec output, and summary, but only if work was needed or done.

3

Print actions, exec output, and summary.

4

Full debug output.

-w seconds

If "-o x" or "-o xi" is selected, ctlinnd will wait seconds seconds before timing out. The default value is "-w 30".

-z seconds

If "-o x" is selected, actsync will pause for seconds seconds before each command is executed. This helps prevent innd from being busied-out if a large number of ctlinnd commands are needed. One can entirely disable this sleeping by using "-z 0". By default, actsync will pause for 4 seconds before each command is executed if "-o x" is selected.

## EXAMPLES
Determine the difference (but don't change anything) between your newsgroup set and uunet's set:

```
    actsync news.uu.net
```

Same as above, with full debug and progress reports:

```
    actsync -v 4 news.uu.net
```

Force a site to have the same newsgroups as some other site:

```
    actsync -o x master
```

This may be useful to sync a slave site to its master, or to sync internal site to a gateway.

Compare your site with uunet, disregarding local groups and certain local differences with uunet. Produce a report if any differences were encountered:

```
    actsync -v 2 -i actsync.ign news.uu.net
```

where actsync.ign contains:

```
    # Don't compare to.* groups as they will differ.
    #
    i       to.*
    # These are our local groups that nobody else
    # (should) carry.  So ignore them for the sake
    # of the compare.
    #
    i       nsa.*
    # These groups are local favorites, so keep them
    # even if uunet does not carry them.
    #
    i       ca.dump.bob.dorman
    i       ca.keep.bob.dorman
    i       alt.tv.dinosaurs.barney.die.die.die
    i       alt.tv.dinosaurs.barney.love.love.love
    i       alt.sounds.*    =alt.binaries.sounds.*
```

To interactively sync against news.uu.net, using the same ignore file:

```
    actsync -o xi -v 2 -i actsync.ign news.uu.net
```

Based on newsgroups that you decided to keep, one could make changes to the actsync.ign file:

```
    # Don't compare to.* groups as they will differ.
    #
    i       to.*
    # These are our local groups that nobody else
    # (should) carry.  So ignore them for the sake
    # of the compare.
    #
    i       nsa.*
    # These groups are local favorites, so keep them
    # even if uunet does not carry them.
    #
    i       ca.dump.bob.dorman
    i       alt.tv.dinosaurs.barney.die.die.die
    i       alt.sounds.*    =alt.binaries.sounds.*
    # Don't sync test groups, except for ones that are
    # moderated or that are under the gnu hierarchy.
    #
    i       *.test
    c       *.test m        # check moderated test groups
    c       gnu.*.test
    c       gnu.test        # just in case it ever exists
```

Automatic processing may be set up by using the following actsync.cfg file:

```
    # Host to sync off of (host2).
    host=news.uu.net
    # Location of the ignore file.
    ignore_file=<pathetc in inn.conf>/actsync.ign
    # Where news articles are kept.
    spool=<patharticles in inn.conf>
    # actsync(8) flags
    #
    # Automatic execs, report if something was done,
    # otherwise don't say anything, don't report
    # uunet active file problems, just ignore
    # the affected entries.
    flags=-o x -v 2 -q 2
```

and then by running actsyncd with the path to the config file:

```
    actsyncd <pathetc>/actsync.cfg
```

The command

```
    actsyncd <pathetc>/actsync.cfg 4 >cmd.log 2>dbg.log
```

will operate in debug mode, not change the active file, write ctlinnd style commands to cmd.log, and write debug statements to dbg.log.

To check only the major hierarchies against news.uu,net, use the following actsync.ign file:

```
    # By default, ignore everything.
    #
    i       *
    # Check the major groups.
    #
    c       alt.*
    c       comp.*
    c       gnu.*
    c       humanities.*
    c       misc.*
    c       news.*
    c       rec.*
    c       sci.*
    c       soc.*
    c       talk.*
```

and the command:

```
    actsync -i actsync.ign news.uu.net
```

To determine the differences between your old active and your current default server:

```
    actsync <pathetc>/active.old -
```

To report but not fix any newsgroup problems with the current active file:

```
    actsync - -
```

To detect any newsgroup errors on your local server, and to remove any *.bork.bork.bork-style silly newsgroup names:

```
    actsync -b 2 - -
```

The active file produced by:

```
    actsync <flags> -o x erehwon.honey.edu
```

is effectively the same as the active file produced by:

```
    cd <pathdb>
    ctlinnd pause 'running actsync'
    rm -f active.new
    actsync <flags> -o a1 erehwon.honey.edu > active.new
    rm -f active.old
    ln active active.old
    mv active.new active
    ctlinnd reload active 'running actsync'
    ctlinnd go 'running actsync'
```

It should be noted that the final method above, pausing the server and simply replacing the active file, may be faster if you are making lots of changes.

## FILES
pathbin/actsync

The C program itself used to synchronize, compare, or merge two active files.

pathbin/actsyncd

The Shell daemon which provides a convenient interface to configure and run actsync.

pathetc/actsync.cfg

The configuration file which specifies the settings to use.

pathetc/actsync.ign

The ignore file which contains a set of synchronization rules that specifies which newsgroups will be checked and which will be ignored.

## CAUTION
Careless use of this tool may result in the unintended addition, change, or removal of newsgroups. You should avoid using the "x" output format until you are sure it will do what you want.

## BUGS
If a newsgroup appears multiple times, actsync will treat all copies as errors. However, if the group is marked for removal, only one rmgroup will be issued.

## HISTORY
Written by Landon Curt Noll <chongo@toad.com> for InterNetNews. Updated to support FTP fetching by David Lawrence <tale@isc.org>. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: actsync.pod 10097 2016-11-04 22:19:07Z iulius $

By Landon Curt Noll <chongo@toad.com> (chongo was here /\../\).

Copyright (c) Landon Curt Noll, 1993. All rights reserved.

Permission to use and modify is hereby granted so long as this notice remains. Use at your own risk. No warranty is implied.

## SEE ALSO
active(5), ctlinnd(8), getlist(8), inn.conf(5), mod-active(8), simpleftp(1).


archive

title: archive(8)

summary: Usenet article archiver

text:
# archive(8)

## NAME
archive - Usenet article archiver

## SYNOPSIS
archive [-cfr] [-a archive] [-i index] [-p pattern] [input]

## DESCRIPTION
archive makes copies of files specified on its standard input. It is normally run either as a channel feed under innd or by a script before news.daily is run.

archive reads the named input file, or standard input if no file is given. The input is taken as a sequence of lines; blank lines and lines starting with a number sign ("#") are ignored. All other lines should specify the token of an article to archive. Every article is retrieved from a token, and the Xref: header is used to determine the target file in the archive directory. You can limit the targets taken from the Xref: header with the -p option.

Files are copied to a directory within the archive directory, patharchive in inn.conf (or some other directory given with -a). The default is to create a hierarchy that mimics a traditional news spool storage of the given articles; intermediate directories will be created as needed. For example, if the input token represents article 2211 in the newsgroup comp.sources.unix, archive will by default store the article as:

```
    comp/sources/unix/2211
```

in the archive area. This can be modified with the -c and -f options.

## OPTIONS
-a archive

If the -a flag is given, its argument specifies the root of the archive area, instead of patharchive in inn.conf.

-c

If the -c flag is given, directory names will be flattened as described under the -f option. Then, additionally, all posts will be concatenated into a single file, appending to that file if it already exists. The file name will be "YYYYMM", formed from the current time when archive is run. In other words, if given an article in comp.sources.unix on December 14th, 1998, the article would be appended to the file:

```
    comp.sources.unix/199812

```

in the archive area.

Articles will be separated by a line containing only "-----------".

-f

If the -f flag is used, directory names will be flattened, replacing the slashes with the periods. In other words, article 2211 in comp.sources.unix will be written to:

```
    comp.sources.unix/2211

```

in the archive area.

-i index

If the -i flag is used, archive will append one line to the file index for each article that it archives. This line will contain the destination file name, the Message-ID: header, and the Subject: header of the message, separated by spaces. If either header is missing (normally not possible if the article was accepted by innd), it will be replaced by "<none>". The headers will be transformed using the same rules as are used to generate overview data (unfolded and then with tabs, CR, and LF replaced by spaces).

-p pattern

Limits the targets taken from the Xref: header to the groups specified in pattern. pattern is a uwildmat(3) pattern matching newsgroups that you wish to have archive handle.

-r

By default, archive sets its standard error to pathlog/errlog. To suppress this redirection, use the -r flag.

## RETURN VALUE
If the input is exhausted, archive will exit with a zero status. If an I/O error occurs, it will try to spool its input, copying it to a file. If there was no input filename, the standard input will be copied to pathoutgoing/archive and the program will exit. If an input filename was given, a temporary file named input.bch (if input is an absolute pathname) or pathoutgoing/input.bch (if the filename does not begin with a slash) is created. Once the input is copied, archive will try to rename this temporary file to be the name of the input file, and then exit.

## EXAMPLES
A typical newsfeeds(5) entry to archive most source newsgroups is as follows:

```
    source-archive!\
        :!*,*sources*,!*wanted*,!*.d\
        :Tc,Wn\
        :<pathbin>/archive -f -i <patharchive>/INDEX
```

Replace <pathbin> and <patharchive> with the appropriate paths.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: archive.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
inn.conf(5), newsfeeds(5).


title: auth_krb5(8)

summary: nnrpd Kerberos\ v5 authenticator

text:
# auth_krb5(8)

## NAME
auth_krb5 - nnrpd Kerberos v5 authenticator

## SYNOPSIS
auth_krb5 [-i instance]

## DESCRIPTION
This program does authentication for nnrpd against a Kerberos v5 KDC. This is NOT real Kerberos authentication using service tickets; instead, a username and password is used to attempt to obtain a Kerberos v5 TGT to confirm that they are valid. As such, this authenticator assumes that nnrpd has been given the user's username and password, and therefore is not as secure as real Kerberos authentication. It generally should only be used with NNTP over TLS to protect the password from sniffing.

Normally, you do not want to use this authenticator. Instead, use ckpasswd with PAM support and configure the nnrpd PAM stack to use a Kerberos PAM module. A full Kerberos PAM module is more sophisticated about how it validates passwords and has a much broader array of options than this authenticator.

## OPTIONS
-i instance

If this option is given, instance will be used as the instance of the principal received from nnrpd and authentication will be done against that principal instead of the base principal. In other words, a principal like "user", when passed to auth_krb5 invoked with "-i nntp", will be transformed into "user/nntp" before attempting Kerberos authentication. Since giving one's password to nnrpd is not as secure as normal Kerberos authentication, this option supports a configuration where all users are given a separate instance just for news authentication with its own password, so their regular account password isn't exposed via NNTP.

## EXAMPLE
The following readers.conf(5) fragment tells nnrpd to authenticate users by attempting to obtain Kerberos v5 TGTs for them, appending an instance of "nntp" to usernames before doing so:

```
    auth kerberos {
        auth: "auth_krb5 -i nntp"
    }
    access kerberos {
        users: "*/nntp"
        newsgroups: example.*
    }
```

Access is granted to the example.* groups for all users who successfully authenticate.

## BUGS
Currently, any username containing realm information (containing "@") is rejected. This is to prevent someone from passing in a username corresponding to a principal in another realm that they have access to and gaining access to the news server via it. However, this is also something that people may wish to do under some circumstances, so there should be a better way of handling it (such as, perhaps, a list of acceptable realms or a -r flag specifying the realm in which to attempt authentication).

It's not clear the right thing to do when the username passed in contains a "/" and -i was also given. Right now, auth_krb5 will create a malformed Kerberos principal with multiple instances and attempt to authenticate against it, which will fail but perhaps not with the best error message.

## HISTORY
Originally written by Christopher P. Lindsey. This documentation was written by Russ Allbery <eagle@eyrie.org> based on Christopher's original README file.

$Id: auth_krb5.pod 9774 2015-01-04 21:50:10Z eagle $

## SEE ALSO
ckpasswd(8), nnrpd(8), readers.conf(5).


batcher

title: batcher(8)

summary: Article batching for InterNetNews

text:
# batcher(8)

## NAME
batcher - Article batching for InterNetNews

## SYNOPSIS
batcher [-rv] [-a articles] [-A total-articles] [-b size] [-B total-size] [-i string] [-N batches] [-p process] [-s separator] host [input]

## DESCRIPTION
batcher reads a list of files and prepares news batches for the specified host. It is generally used to prepare UUCP feeds, but the resulting batches can be used by any application that uses rnews(8) to inject the articles. It is normally invoked by a script run out of cron that uses shlock to lock the host, followed by ctlinnd to flush the batch file. See send-uucp(8) for a front-end for batcher.

batcher reads the file input, or standard input if no file is given. If input is a relative file name, it is assumed to be in pathoutgoing as set in inn.conf. Blank lines and lines starting with a number sign ("#") are ignored. All other lines in the input should consist of one or two fields separated by a single space. The first field is the storage API token of an article. The second field, if present, specifies the size of the article in bytes.

By default, batches are written to standard output (which isn't very useful if more than one batch is output), but see the -p option.

## OPTIONS
-a articles

This flag limits the number of articles included in each batch. The default is no limit. A new batch will be started when either the total bytes or the number of articles written exceeds the specified limits.

-A total-articles

Limits the total number of articles written for all batches. As soon as the total number of articles written to batches reaches or exceeds total-articles, all additional articles in the input will be deferred. The default is no limit.

-b size

This flag sets the size limit for each batch; as soon as at least this much data has been written out, a new batch will be started. The default size is 60 KB. Using "-b 0" will allow unlimited batch sizes.

-B total-size

Limits the total number of bytes written for all batches. As soon as the total bytes written to batches reaches or exceeds total-size, all additional articles in the input will be deferred. The default is no limit.

-i string

A batch starts with an identifying line to specify the unpacking method to be used on the receiving end. When this flag is used, string, followed by a newline, will be output at the start of each batch. The default is to have no initial string (under the assumption that either the processor specified with the -p flag or some other later process will add the appropriate line).

-N batches

Limits the total number of batches written. As soon as the number of batches written reaches or exceeds batches, all additional articles in the input will be deferred. The default is no limit.

-p process

By default, batches are written to standard output, which is not useful when more than one output batch is created. If this option is given, each batch will instead be fed via a pipe to the shell command process. The process argument must be an sprintf(3) format string, which may have a single %s parameter that will be replaced with the host name. A common value is:

```
    ( echo '#! gunbatch' ; exec gzip -c ) | uux - -r -z %s!rnews

```

which generates gzip-compressed batches and feeds them to uux.

-r

By default, batcher reports errors to pathlog/errlog. To suppress this redirection and report errors to standard error, use the -r flag.

-s separator

Each article in a batch starts with a separator line that indicates the size of the article. separator must be an sprintf(3) string, which may have a single %ld in the string that will be replaced with the size of the article. If the separator is not empty, a newline will also be appended to it when it is added to the beginning of each article. The default separator is:

```
    #! rnews %ld

```

and this should rarely be changed.

-v

Upon exit, batcher reports statistics via syslog. With this flag, the statistics will also be printed to standard output.

## EXIT STATUS
If the input is exhausted and all batches are created successfully, batcher will exit with a zero status.

If any of the limits specified with -A, -B, or -N flags are reached, or if there is an error in writing a batch, batcher will try to spool the remaining input by copying it to a file as follows:

- If there was no input filename, the remaining input will be copied to pathoutgoing/host.

- If an input filename was given, the remaining input will be copied to a temporary file named by appending ".bch" to the end of input (and qualified by adding pathoutgoing if input was not a fully qualified path). If this happens successfully, batcher will then try to rename this temporary file to input (thus replacing input with a copy of itself with all of lines for the successfully batched articles removed).

Upon receipt of an interrupt or termination signal, batcher will finish batching the current article, close the batch, and then rewrite the batch file as described above.

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten by Russ Allbery <eagle@eyrie.org> in POD.

$Id: batcher.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
ctlinnd(8), inn.conf(5), newsfeeds(5), rnews(8), send-uucp(8), shlock(1).


buffchan

title: buffchan(8)

summary: Buffered file\-writing backend for INN

text:
# buffchan(8)

## NAME
buffchan - Buffered file-writing backend for INN

## SYNOPSIS
buffchan [-bru] [-c lines] [-C seconds] [-d directory] [-f num-fields] [-l lines] [-L seconds] [-m map] [-p pid-file] [-s format]

## DESCRIPTION
buffchan reads lines from standard input and copies the initial fields in each line to the files named by the remaining fields on the line. buffchan is intended to be called by innd as an exploder feed.

The input is interpreted as a sequence of lines. Each line contains a fixed number of initial fields, followed by a variable number of filename fields. All fields in a line are separated by whitespace and do not contain any whitespace. The default number of initial fields is one.

For each line of input, buffchan writes the initial fields, separated by a space and followed by a newline, to each of the files named in the filename fields. The output files are kept open and are only flushed or closed based on the schedule given by the -c, -C, -l, and -L options.

As an exploder feed (see newsfeeds(5) for an explanation), buffchan interprets lines beginning with an exclamation point as commands. Besides "!begin" (which only marks the start of the feed), there are three supported commands:

!flush [site]

The flush command closes and reopens all open files. An optional site can be specified, in which case buffchan flushes only that file. This command is analogous to the "ctlinnd flush" command. This command can be sent via innd using "ctlinnd send buffchan-site 'flush site'". Applications can tell that flush has completed by renaming the file before issuing the command. When the original file name has reappeared, the flush is complete. If fchmod(3) is available, buffchan also changes the file to read-only while it's actively writing to it and changes it back to read/write once it has been closed. It will change the mode back to read-only only if it reopens the same file.

!drop [site]

The drop command is similar to the flush command, except that no files are reopened. If given an argument, only the specified site is dropped; otherwise, all sites are dropped. (Note that a site will be restarted if the input stream mentions the site again.) When a "ctlinnd drop site" command is sent, innd will automatically forward the command to buffchan if the site is listed as a funnel feeding into the buffchan exploder. To drop all sites, use "ctlinnd send buffchan-site drop".

!readmap

The map file specified with the -m option, if given, will be reloaded.

Once buffchan opens a file, it keeps it open (in the absence of a drop command). The input must therefore never specify more files than the maximum number of files a process may open.

## OPTIONS
-b

Force the output to be buffered. (This is generally the default, but it may depend on the operating system.) If -b is given, a buffer size of BUFSIZ (a constant of the system standard I/O library) is used.

-c lines

If the -c flag is given, buffchan will close and reopen a file after every lines lines are written to the file.

-C seconds

If the -C flag is given, buffchan will close and reopen a file if it has been open for more than seconds seconds.

-d directory

This flag may be used to specify a directory the program should change to before starting. If this flag is used, the default for the -s flag (see below) is changed to be a simple %s (in other words, output files are considered to be relative to directory).

-f num-fields

By default, each line is expected to contain one fixed field followed by some number of filename fields. If this flag is given, num-fields will be used as the number of initial fixed fields.

-l lines

If the -l flag is given, buffchan will flush the output after every lines lines are written to a file.

-L seconds

If the -L flag is given, buffchan will flush each output file every seconds seconds.

-m map

Map files translate the names in the filename fields on each line into filenames that should be used instead. It's used primarily when short names are used in newsfeeds, but the output files should use the full domain names of remote peers. In the map file, blank lines and lines starting with a number sign ("#") are ignored. All other lines should have two host names separated by a colon. The first field is the name that may appear in the input stream; the second field names the file to be used when the name in the first field appears. For example:

```
    # This is a comment
    uunet:news.uu.net
    foo:foo.com
    munnari:munnari.oz.au

```

-p pid-file

If the -p option is given, buffchan will write a line containing its process ID (in text) to the specified file when it starts.

-r

By default, buffchan sends its error messages to pathlog/errlog. To suppress this redirection and send error messages to standard error, use the -r flag.

-s

The -s flag may be used to specify a format that maps a filename from the filename fields at the end of each line to an actual filename. This is a sprintf(3) format string that should contain a single instance of %s, which will be replaced with the value of the filename field (possibly after mapping with the map file from -m). The default value is pathoutgoing/%s.

-u

If the -u flag is used, the output will be unbuffered.

## EXAMPLES
If buffchan is invoked with "-f 2" and given the following input:

```
    news/software/b/132 <1643@munnari.oz.au> foo uunet
    news/software/b/133 <102060@litchi.foo.com> uunet munnari
    comp/sources/unix/2002 <999@news.foo.com> foo uunet munnari
```

Then the file foo will have these lines:

```
    news/software/b/132 <1643@munnari.oz.au>
    comp/sources/unix/2002 <999@news.foo.com>
```

the file munnari will have these lines:

```
    news/software/b/133 <102060@litchi.foo.com>
    comp/sources/unix/2002 <999@news.foo.com>
```

and the file uunet will have these lines:

```
    news/software/b/132 <1643@munnari.oz.au>
    news/software/b/133 <102060@litchi.foo.com>
    comp/sources/unix/2002 <999@news.foo.com>
```

## HISTORY
Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Converted to POD by Russ Allbery <eagle@eyrie.org>.

$Id: buffchan.pod 9767 2014-12-07 21:13:43Z iulius $

## SEE ALSO
ctlinnd(8), filechan(8), inn.conf(5), innd(8), newsfeeds(5).