.\" .\" *********************************************************************
.\" .\" *                                                                   *
.\" .\" *             Copyright 2020-2022, Intel Corporation                *
.\" .\" *                                                                   *
.\" .\" *                       All Rights Reserved.                        *
.\" .\" *                                                                   *
.\" .\" *********************************************************************

.TH ethfabricanalysis 8 "Intel Corporation" "Copyright(C) 2020\-2022" "EFSFFCLIRG (Man Page)"
.SH NAME
ethfabricanalysis


.PP
Performs analysis of the fabric.
.SH Syntax
ethfabricanalysis [-b|-e] [-s] [-d  \fIdir\fR] [-c  \fIfile\fR]
[-E  \fIfile\fR] [-p  \fIplanes\fR] [-T  \fItopology\(ulinputs\fR] [-f  \fIhost\(ulfiles\fR]
.SH Options

.TP 10
--help

Produces full help text.
.TP 10
-b

Specifies the baseline mode. Default is compare/check mode.
.TP 10
-e

Evaluates health only. Default is compare/check mode.
.TP 10
-s

Saves history of failures (errors/differences).
.TP 10
-d \fIdir\fR

Specifies the top-level directory for saving baseline and history of failed checks. Default is /var/usr/lib/eth-tools/analysis
.TP 10
-c \fIfile\fR

Specifies the error thresholds config file.Default is /etc/eth-tools/ethmon.conf
.TP 10
-E \fIfile\fR

Specifies Ethernet Mgt configuration file. The default is /etc/eth-tools/mgt\(ulconfig.xml.

.TP 10
-p \fIplanes\fR

Specifies Fabric planes separated by space. The default is the first enabled plane defined in config file. Value \[aq]ALL\[aq] will use all enabled planes.

.TP 10
-f \fIhost\(ulfiles\fR

Hosts files separated by space. It overrides the HostsFiles defined in Mgt config file for the corresponding planes. Value \[aq]DEFAULT\[aq] will use the HostFile defined in Mgt config file for the corresponding plane

.TP 10
-T \fItopology\(ulinputs\fR

Specifies the name of topology input filenames separated by space. See
\fIDetails\fR
and
\fIethreport\fR
for more information.
.SH Example
ethfabricanalysis
.br

ethfabricanalysis -p \[aq]p1 p2\[aq] -f \[aq]hosts1 DEFAULT\[aq]
.PP
The fabric analysis tool checks the following:
.IP \(bu
Fabric links (both internal to switch and external cables)
.IP \(bu
Fabric components (nodes, links, systems, and their configuration)
.IP \(bu
Fabric error counters and link speed mismatches
.PP

.B NOTE:
The comparison includes components on the fabric. Therefore, operations such as shutting down a server cause the server to no longer appear on the fabric and are flagged as a fabric change or failure by ethfabricanalysis.

.SH Environment Variables

.PP
The following environment variables are also used by this command:
.TP 10
\fBFF\(ulANALYSIS\(ulDIR\fR

Top-level directory for baselines and failed health checks.
.SH Details

.PP
You can specify the topology\(ulinput file to be used with one of the following methods:
.IP \(bu
On the command line using the -T option.
.IP \(bu
Using the TopologyFile specified in Ethernet Mgt config file.
.PP
If the specified file does not exist, no topology\(ulinput file is used.
.PP
For more information on topology\(ulinput, refer to
\fIethreport\fR
.
.PP
By default, the error analysis includes counters and slow links (that is, links running below enabled speeds). You can change this using the \fBFF\(ulFABRIC\(ulHEALTH\fR configuration parameter in ethfastfabric.conf. This parameter specifies the ethreport options and reports to be used for the health analysis.
.PP
When a topology\(ulinput file is used, it can also be useful to extend \fBFF\(ulFABRIC\(ulHEALTH\fR to include fabric topology verification options such as -o verifylinks.
.PP
The thresholds for counter analysis default to /etc/eth-tools/ethmon.conf. However, you can specify an alternate configuration file for thresholds using the -c option. The ethmon.si.conf file can also be used to check for any non-zero values for signal integrity (SI) counters.
.PP
All files generated by ethfabricanalysis start with fabric in their file name.
.PP
The ethfabricanalysis tool generates files such as the following within FF\(ulANALYSIS\(ulDIR :
.PP

\fBHealth Check\fR

.IP \(bu
latest/fabric.<plane\(ulname>.errors stdout of ethreport for errors encountered during fabric error analysis.

.IP \(bu
latest/fabric.<plane\(ulname>.errors.stderr stderr of ethreport during fabric error analysis.

.PP

\fBBaseline\fR

.PP
During a baseline run, the following files are also created in FF\(ulANALYSIS\(ulDIR/latest.
.IP \(bu
baseline/fabric.<plane\(ulname>.snapshot.xml ethreport snapshot of complete fabric components and configuration.

.IP \(bu
baseline/fabric.<plane\(ulname>.comps ethreport summary of fabric components and basic configuration.

.IP \(bu
baseline/fabric.<plane\(ulname>.links ethreport summary of internal and external links.

.PP

\fBFull Analysis\fR

.IP \(bu
latest/fabric.<plane\(ulname>.snapshot.xml ethreport snapshot of complete fabric components and configuration.

.IP \(bu
latest/fabric.<plane\(ulname>.snapshot.stderr stderr of ethreport during snapshot.

.IP \(bu
latest/fabric.<plane\(ulname>.errors stdout of ethreport for errors encountered during fabric error analysis.

.IP \(bu
latest/fabric.<plane\(ulname>.errors.stderr stderr of ethreport during fabric error analysis.

.IP \(bu
latest/fabric.<plane\(ulname>.comps stdout of ethreport for fabric components and configuration.

.IP \(bu
latest/fabric.<plane\(ulname>.comps.stderr stderr of ethreport for fabric components.

.IP \(bu
latest/fabric.<plane\(ulname>.comps.diff diff of baseline and latest fabric components.

.IP \(bu
latest/fabric.<plane\(ulname>.links stdout of ethreport summary of internal and external links.

.IP \(bu
latest/fabric.<plane\(ulname>.links.stderr stderr of ethreport summary of internal and external links.

.IP \(bu
latest/fabric.<plane\(ulname>.links.diff diff of baseline and latest fabric internal and external links.

.IP \(bu
latest/fabric.<plane\(ulname>.links.changes.stderr stderr of ethreport comparison of links.

.IP \(bu
latest/fabric.<plane\(ulname>.links.changes ethreport comparison of links against baseline. This is typically easier to read than the links.diff file and contains the same information.

.IP \(bu
latest/fabric.<plane\(ulname>.comps.changes.stderr stderr of ethreport comparison of components.

.IP \(bu
latest/fabric.<plane\(ulname>.comps.changes ethreport comparison of components against baseline. This is typically easier to read than the comps.diff file and contains the same information.

.PP
The .diff and .changes files are only created if differences are detected.
.PP
If the -s option is used and failures are detected, files related to the checks that failed are also copied to the time-stamped directory name under FF\(ulANALYSIS\(ulDIR.
.SH Fabric Items Checked Against the Baseline

.PP
Based on ethreport -o links:
.IP \(bu
Unconnected/down/missing cables
.IP \(bu
Added/moved cables
.IP \(bu
Changes in link width and speed
.IP \(bu
Changes to IfAddr in fabric (replacement of NIC or Switch hardware)
.IP \(bu
Adding/Removing Nodes [NIC, Virtual NICs, Virtual Switches, Physical Switches, Physical Switch internal switching cards (leaf/spine)]
.IP \(bu
Changes to server or switch names
.PP
Based on ethreport -o comps:
.IP \(bu
Overlap with items from links report
.IP \(bu
Changes in port MTU
.IP \(bu
Changes in port speed/width enabled or supported
.IP \(bu
Changes in NIC or switch device IDs/revisions/VendorID (for example, ASIC hardware changes)
.IP \(bu
Changes in port Capability mask (which features/agents run on port/server)
.IP \(bu
Changes to IOUs/IOCs/IOC Services provided


.SH Fabric Items Also Checked During Health Check

.PP
Based on ethreport -s -o errors -o slowlinks:
.IP \(bu
error counters on all Intel(R) Ethernet Fabric ports (NIC, switch external and switch internal) checked against configurable thresholds.
.IP \(bu
Typically identifies potential fabric errors, such as symbol errors.
.IP \(bu
May also identify transient congestion, depending on the counters that are monitored.
.IP \(bu
Link active speed/width as compared to Enabled speed.
.IP \(bu
Identifies links whose active speed/width is < min (enabled speed/width on each side of link).
.IP \(bu
This typically reflects bad cables or bad ports or poor connections.
.IP \(bu
Side effect is the verification of fabric health.
