DocWiki - User contributions [en]

Migrating from Cisco FWSM to Cisco ASA Software

2009-08-31T16:48:43Z

Lorlando:

This document outlines the differences between Cisco FWSM 4.0(1) and Cisco ASA 8.2(1) software to provide users with information to use when making the decision to migrate from FWSM to ASA software. It does not explain how to migrate from using a Cisco FWSM to using a Cisco ASA device. Features that are in FWSM but not in ASA are described, as well as features that are available on both platforms but implemented differently. Features that are in ASA but are not available in FWSM are not listed.

This wiki includes the following sections:
* [[Implicit Behavioral Differences]]
* [[Feature Differences]]
* [[Configuration Command Differences]]
* [[Exec Command Differences]]
* [[clear Command Differences]]
* [[show Command Differences]]
* [[Exec and Unsaved Config Command Differences]]
* [[Default Value and Value Range Differences]]
* [[SNMP Differences]]
* [[System Log Message Differences]]

System Log Message Differences

2009-08-28T22:29:40Z

Lorlando:

==System Log Message Differences==
The following system log messages are deprecated in ASA but not in FWSM:

1. %FWSM-6-303003: FTP cmd_name command denied - failed strict
:inspection, terminating connection from
:source_interface:source_address/source_port to
:dest_interface:dest_address/dest_port
2. %FWSM-4-313003: Invalid destination for ICMP error

The following system log messages are present in FWSM but not in ASA:

1. %FWSM-6-106028: Deny TCP (Connection marked for deletion)
:from src ip-address/src-port to dst ip-address/dst-port
:flags flag on interface intf-name

2. %FWSM-4-109036: Teardown protocol connection session_id for
:src_if:src_ip/src_port to dest_if:dest_ip/dest_port
:duration duration bytes bytes due to Uauth timeout

3. %FWSM-4-109037: Authentication cannot be done for the user
:from src_ip to dest_ip for application since auth_proto
:client is too busy

4. %FWSM-4-109039: Func_ID: Uauth Unproxy Failed due to the
:reason: Failed_Reason

5. %FWSM-3-202012: Connection rate limit exceeded conns/rate-limit
:(per seconds) for dir packet from source_address/source_port to
:dest_address/dest_port on interface interface_name

6. %FWSM-6-302022: Built IP protocol 103 connection 219025360
:for int_112:172.16.2.1 (172.16.2.1) to int_102:172.16.112.2
:(172.16.112.2)

7. %FWSM-6-302023: Teardown IP protocol 103 connection
:219025359 for int_102:172.16.2.1 to int_112:172.16.112.2
:duration 0:00:35 bytes 74

8. FWSM-6-622002:%d: Teardown BGP Peering session with %A
:and AS #%d\n, BGP_PEER_SES_TEAR_DOWN

9. %FWSM-2-709008: Configuration may be out of sync between
:Active/Standby units

The following table shows system log messages that are present in both FWSM and ASA software, but the text in FWSM software is different from that in ASA software.

{| border="1" cellpadding="2"
!width="450" align="left" style="background:#99CCFF;" |'''FWSM'''
!width="450" align="left" style="background:#99CCFF;" |'''ASA'''
|-
|-
|%FWSM-6-302024: Pre-allocated H323 GUP connection for faddr intf: {foreign-address /foreign-port} to laddr intf: {local-address/local-port}
||%ASA-6-302033:Pre-allocated H323 GUP Connection for faddr interface:foreign address/foreign-port to laddr interface:local-address/local-port
|-
|%FWSM-4-302025: Unable to Pre-allocate H323 GUP Connection for faddr
intf: {foreign-address/foreign-port} to laddr intf: {local-address/local-port}
|%ASA-4-302034: Unable to pre-allocate H323 GUP Connection for faddr
interface: foreign address/foreign-port to laddr
interface:local-address/local-port
|-
|%FWSM-4-109035: Authentication failed for user username as the password expired
|%ASA-3-109035: Exceeded maximum number (999) of DAP attribute instances for user string.
|-
|%FWSM-6-609001: Built local-hostinterface_name:IP_address
|%ASA-7-609001: Built local-hostinterface_name:IP_address
|-
|%FWSM-6-609002: Teardown local-host interface_name:IP_address duration time
|%ASA-7-609002: Teardown local-host interface_name:IP_address duration time
|-
|FWSM-6-622001:%d: Built BGP Peering session with %A and AS #%d\n, BGP_PEER_SES_ESTABLISH
|%ASA-6-622001: string tracked route network mask address, distance number, table string, on interface interface-name
|-
|}

Feature Differences

2009-08-28T22:27:58Z

Lorlando: /* Feature Differences */

==Feature Differences==
The following table lists the feature differences between FWSM and ASA.
{| border="1" cellpadding="2"
!width="250" align="left" style="background:#99CCFF;" |'''Feature'''
!width="450" align="left" style="background:#99CCFF;" |'''FWSM Description'''
!width="250" align="left" style="background:#99CCFF;" |'''ASA Description'''
|-
|Authentication support when sessioning to system context in multiple mode
'''aaa authentication telnet console''' command from admin context
|In multi mode AAA commands cannot be configured in system context. However, telenet authenication in admin context is used for authenticating sessions from the supervisor engines that enter system context.
|Does not have session command support, so AAA authentication in the admin context is not used by the system context.
|-
|IPSec in multimode
(managment only)
|IPSec is supported for management purposed in multimode.
|No IPSec support in multimode.
|-
|Mixed mode support
CLI:
'''firewall transparent'''
|This is a feature in FWSM in which the firewall mode can be set in each context in multimode.
|Not supported in ASA, and the firewall mode is set for the entire device.
|-
|Bridge Groups
CLI:
'''bridge-group interface bvi'''
|This feature in FWSM increased the number of interfaces in transparent mode to eight pairs from a single pair.
|Not supported in ASA.
|-
|Asymmetric Routing
(non active/active mode)
|When asymmetic routing was introduced in FWSM, the active/active restriction that is present in ASA was removed.
|Supported in active/active mode only.
|-
|BGP Stub Routing
CLI:
'''router bgp'''
'''bgp router-id'''
'''neighbor remote-as'''
'''neighbor password'''
'''network'''
|Supported in FWSM.
|Not supported in ASA.
|-
|Failover preemption for active/standby failover
|FWSM can be configured in an active/standby scenario. When configured, the primary unit always becomes active after a certain time in the following cases:
1. When the primary unit fails and the secondary unit becomes active.

2. When the secondary unit boots before the primary unit, and the secondary unit becomes active.
|Not supported in ASA.
|-
|Trusted Flow Acceleration
CLI:
'''service-acceleration'''
'''set connect'''
'''advanced options'''
|This feature lets the FWSM take advantage of the processing power of the switch supervisor engine that allows for increased throughput by installing EARL shortcuts.
|Not supported in ASA.
|-
|Route Health Inspection
CLI:
'''redistribute connected'''
'''redistribute nat'''
'''redistribute static'''
'''route-inject'''
|This feature installs connected, static, NAT pool routes configured on the FWSM into MSFC on a per-contxt basis. MSFC can then redistribute the routes.
|Not supported in ASA.
|-
|PISA Integration
CLI:
'''deny'''
'''permit'''
|The FWSM uses this feature to leverage the high-performance deep packet inspection of the PISA card so that it can permit or deny traffic based on the application type.
|Not supported in ASA.
|-
|DHCP Relay interface specific servers
CLI:
'''dhcprelay server''' <''ip_address''>
'''interface vlan''' <''vlan id''>
|FWSM added this feature in 3.2(1). With this feature, users can configure interface specific DHCP servers. The '''dhcprelay server''' command can be configured in global mode and in interface specific mode.
|Not supported in ASA.
|-
|Stateful Failover Uauth Table Replication
|FWSM supports replicating Uauth Table in the failover peer when stateful failover is configured.
|Not supported in ASA.
|}

Migrating from Cisco FWSM to Cisco ASA Software

2009-08-28T21:56:21Z

Lorlando:

This document outlines the differences between Cisco FWSM 4.0(1) and Cisco ASA 8.2(1) software to provide users with information to use when making the decision to migrate from FWSM to ASA software. Features that are in FWSM but not in ASA are described, as well as features that are available on both platforms but implemented differently. Features that are in ASA but are not available in FWSM are not listed.

This wiki includes the following sections:
* [[Implicit Behavioral Differences]]
* [[Feature Differences]]
* [[Configuration Command Differences]]
* [[Exec Command Differences]]
* [[clear Command Differences]]
* [[show Command Differences]]
* [[Exec and Unsaved Config Command Differences]]
* [[Default Value and Value Range Differences]]
* [[SNMP Differences]]
* [[System Log Message Differences]]

System Log Message Differences

2009-08-28T21:55:19Z

Lorlando:

==System Log Message Differences==
The following system log messages are deprecated in ASA but not in FWSM:

1. %FWSM-6-303003: FTP cmd_name command denied - failed strict
:inspection, terminating connection from
:source_interface:source_address/source_port to
:dest_interface:dest_address/dest_port
2. %FWSM-4-313003: Invalid destination for ICMP error

The following system log messages are present in FWSM but not in ASA:

1. %FWSM-6-106028: Deny TCP (Connection marked for deletion)
:from src ip-address/src-port to dst ip-address/dst-port
:flags flag on interface intf-name

2. %FWSM-4-109036: Teardown protocol connection session_id for
:src_if:src_ip/src_port to dest_if:dest_ip/dest_port
:duration duration bytes bytes due to Uauth timeout

3. %FWSM-4-109037: Authentication cannot be done for the user
:from src_ip to dest_ip for application since auth_proto
:client is too busy

4. %FWSM-4-109039: Func_ID: Uauth Unproxy Failed due to the
:reason: Failed_Reason

5. %FWSM-3-202012: Connection rate limit exceeded conns/rate-limit
:(per seconds) for dir packet from source_address/source_port to
:dest_address/dest_port on interface interface_name

6. %FWSM-6-302022: Built IP protocol 103 connection 219025360
:for int_112:172.16.2.1 (172.16.2.1) to int_102:172.16.112.2
:(172.16.112.2)

7. %FWSM-6-302023: Teardown IP protocol 103 connection
:219025359 for int_102:172.16.2.1 to int_112:172.16.112.2
:duration 0:00:35 bytes 74

8. FWSM-6-302026: Built dir Service-Accelerated connection
:connection_id from interface:src-address/src-port (mapped-
:src-address/mapped-src-port to interface:dst-address/dst-port
:(mapped-dst-address/mapped-dst-port)

9. FWSM-6-302027: Teardown Service-Accelerated connection
:connection_id from interface:src-address/src-port to
:interface:dst-address/dst-port

10. FWSM-6-622002:%d: Teardown BGP Peering session with %A
:and AS #%d\n, BGP_PEER_SES_TEAR_DOWN

11. %FWSM-2-709008: Configuration may be out of sync between
:Active/Standby units

The following table shows system log messages that are present in both FWSM and ASA software, but the text in FWSM software is different from that in ASA software.

{| border="1" cellpadding="2"
!width="450" align="left" style="background:#99CCFF;" |'''FWSM'''
!width="450" align="left" style="background:#99CCFF;" |'''ASA'''
|-
|-
|%FWSM-6-302024: Pre-allocated H323 GUP connection for faddr intf: {foreign-address /foreign-port} to laddr intf: {local-address/local-port}
||%ASA-6-302033:Pre-allocated H323 GUP Connection for faddr interface:foreign address/foreign-port to laddr interface:local-address/local-port
|-
|%FWSM-4-302025: Unable to Pre-allocate H323 GUP Connection for faddr
intf: {foreign-address/foreign-port} to laddr intf: {local-address/local-port}
|%ASA-4-302034: Unable to pre-allocate H323 GUP Connection for faddr
interface: foreign address/foreign-port to laddr
interface:local-address/local-port
|-
|%FWSM-4-109035: Authentication failed for user username as the password expired
|%ASA-3-109035: Exceeded maximum number (999) of DAP attribute instances for user string.
|-
|%FWSM-6-609001: Built local-hostinterface_name:IP_address
|%ASA-7-609001: Built local-hostinterface_name:IP_address
|-
|%FWSM-6-609002: Teardown local-host interface_name:IP_address duration time
|%ASA-7-609002: Teardown local-host interface_name:IP_address duration time
|-
|FWSM-6-622001:%d: Built BGP Peering session with %A and AS #%d\n, BGP_PEER_SES_ESTABLISH
|%ASA-6-622001: string tracked route network mask address, distance number, table string, on interface interface-name
|-
|}

System Log Message Differences

2009-08-28T21:52:53Z

Lorlando: New page: ==System Log Message Differences== The following system log messages are deprecated in ASA but not in FWSM: 1. %FWSM-6-303003: FTP cmd_name command denied - failed strict :inspection, te...

==System Log Message Differences==
The following system log messages are deprecated in ASA but not in FWSM:

1. %FWSM-6-303003: FTP cmd_name command denied - failed strict
:inspection, terminating connection from
:source_interface:source_address/source_port to
:dest_interface:dest_address/dest_port
2. %FWSM-4-313003: Invalid destination for ICMP error

The following system log messages are present in FWSM but not in ASA:

1. %FWSM-6-106028: Deny TCP (Connection marked for deletion)
:from src ip-address/src-port to dst ip-address/dst-port
:flags flag on interface intf-name

2. %FWSM-4-109036: Teardown protocol connection session_id for
:src_if:src_ip/src_port to dest_if:dest_ip/dest_port
:duration duration bytes bytes due to Uauth timeout

3. %FWSM-4-109037: Authentication cannot be done for the user
:from src_ip to dest_ip for application since auth_proto
:client is too busy

4. %FWSM-4-109039: Func_ID: Uauth Unproxy Failed due to the
:reason: Failed_Reason

5. %FWSM-3-202012: Connection rate limit exceeded conns/rate-limit
:(per seconds) for dir packet from source_address/source_port to
:dest_address/dest_port on interface interface_name

6. %FWSM-6-302022: Built IP protocol 103 connection 219025360
:for int_112:172.16.2.1 (172.16.2.1) to int_102:172.16.112.2
:(172.16.112.2)

7. %FWSM-6-302023: Teardown IP protocol 103 connection
:219025359 for int_102:172.16.2.1 to int_112:172.16.112.2
:duration 0:00:35 bytes 74

8. FWSM-6-302026: Built dir Service-Accelerated connection
:connection_id from interface:src-address/src-port (mapped-
:src-address/mapped-src-port to interface:dst-address/dst-port
:(mapped-dst-address/mapped-dst-port)

9. FWSM-6-302027: Teardown Service-Accelerated connection
:connection_id from interface:src-address/src-port to
:interface:dst-address/dst-port

10. FWSM-6-622002:%d: Teardown BGP Peering session with %A
:and AS #%d\n, BGP_PEER_SES_TEAR_DOWN

11. %FWSM-2-709008: Configuration may be out of sync between
:Active/Standby units

The following table shows system log messages that are present in both FWSM and ASA software, but the text in FWSM software is different from that in ASA software.

{| class="wikitable"
|-
! FWSM
! ASA
|-
|%FWSM-6-302024: Pre-allocated H323 GUP connection for faddr intf: {foreign-address /foreign-port} to laddr intf: {local-address/local-port}
||%ASA-6-302033:Pre-allocated H323 GUP Connection for faddr interface:foreign address/foreign-port to laddr interface:local-address/local-port
|-
|%FWSM-4-302025: Unable to Pre-allocate H323 GUP Connection for faddr
intf: {foreign-address/foreign-port} to laddr intf: {local-address/local-port}
|%ASA-4-302034: Unable to pre-allocate H323 GUP Connection for faddr
interface: foreign address/foreign-port to laddr
interface:local-address/local-port
|-
|%FWSM-4-109035: Authentication failed for user username as the password expired
|%ASA-3-109035: Exceeded maximum number (999) of DAP attribute instances for user string.
|-
|%FWSM-6-609001: Built local-hostinterface_name:IP_address
|%ASA-7-609001: Built local-hostinterface_name:IP_address
|-
|%FWSM-6-609002: Teardown local-host interface_name:IP_address duration time
|%ASA-7-609002: Teardown local-host interface_name:IP_address duration time
|-
|FWSM-6-622001:%d: Built BGP Peering session with %A and AS #%d\n, BGP_PEER_SES_ESTABLISH
|%ASA-6-622001: string tracked route network mask address, distance number, table string, on interface interface-name
|-
|}

SNMP Differences

2009-08-28T21:50:44Z

Lorlando: New page: ==SNMP Differences== The following list shows MIBs that are supported by FWSM but not supported by ASA: *CISCO-ENTITY-ALARM-MIB.my *CISCO-ENTITY-REDUNDANCY-MIB.my *CISCO-ENTITY-REDUNDAN...

==SNMP Differences==
The following list shows MIBs that are supported by FWSM but not supported by ASA:

*CISCO-ENTITY-ALARM-MIB.my

*CISCO-ENTITY-REDUNDANCY-MIB.my

*CISCO-ENTITY-REDUNDANCY-TC-MIB.my

*CISCO-L4L7MODULE-RESOURCE-LIMIT-MIB.my

*CISCO-NAT-EXT-MIB.my

*NAT-MIB.my

*TCP-MIB.my

*UDP-MIB.my

The following list shows traps that are supported by FWSM but not suported by ASA:

*ceAlarmAsserted: CISCO-ENTITY-ALARM-MIB.my

*ceRedunEventSwitchover: CISCO-ENTITY-REDUNDANCY-MIB.my

*clrResourceLimitReached: CISCO-L4L7MODULE-RESOURCE-LIMIT-MIB.my

*clrResourceRateLimitReached: CISCO-L4L7MODULE-RESOURCE-LIMIT-MIB.my

*cpmCPURisingThreshold: CISCO-PROCESS-MIB.MY

*natPacketDiscard: NAT-MIB.my

Default Value and Value Range Differences

2009-08-28T21:49:01Z

Lorlando: New page: ==Default Value and Value Range Differences== The following table lists the differences in default values and value ranges between ASA and FWSM. {| border="1" cellpadding="2" !align="cente...

==Default Value and Value Range Differences==
The following table lists the differences in default values and value ranges between ASA and FWSM.
{| border="1" cellpadding="2"
!align="center" style="background:#99CCFF;" |'''FWSM'''
!align="center" style="background:#99CCFF;" |'''ASA'''
|-
| Minimum failover poll time is 500 milliseconds.
CLI:
'''failover polltime msec'''
| Minimum failover poll time in milliseconds is 200.
CLI:
'''failover polltime msec'''
|-
|Minimum poll interval for interfaces is 3 seconds.
CLI:
'''failover polltime interface'''
|Minimum poll interval for interfaces is 1 second. ASA also supports milliseconds and the minimum millisec interval is 500.
CLI:
'''failover polltime interval'''
'''failover polltime interval msec'''
|-
|Minimum failover unit poll time is 500 milliseconds.
CLI:
'''failover polltime unit msec'''
|Miminum failover unit poll time is 200 milliseconds.
CLI:
'''failover polltime unit msec'''
|-
|Resource limits:

Conns = 999,900

Cons/Sec = 102,400

Fixups/Sec = 10,000

Hosts = 256K

Syslogs/sec = 30,000

Xlates = 256K
|ASA does not have resource limits for the resources mentioned in the FWSM column.
|-
|SIP Disconnect Timeout:
minimum = 1 minute

maximum = 10 minutes

CLI:
'''timeout sip-disconnect'''
|SIP Disconnect Timeout:
mimimum = 1 minute

maximum = 1193 minutes

CLI:
'''timeout sip-disconnect'''
|-
|SIP Invite Timeout:
maximum = 30 minutes

CLI:
'''timeout sip-invite'''
|SIP Invite Timeout:
maximum = 1193 minutes

CLI:
'''timeout sip-invite'''
|-
|XLATE Timeout:
mimimum = 30 seconds

CLI:
'''timeout xlate'''

|Xlate Timeout:
minimum = 1 minute

CLI:
'''timeout xlate'''
|-
|}

Exec and Unsaved Config Command Differences

2009-08-28T21:48:04Z

Lorlando: New page: ==Exec and Unsaved Config Command Differences== The following table lists the Exec and configuration commands (not saved in the startup config) that are in FWSM software but not in ASA so...

==Exec and Unsaved Config Command Differences==

The following table lists the Exec and configuration commands (not saved in the startup config) that are in FWSM software but not in ASA software.
{| border="1"
|-
|align="left" | '''access-list commit'''
|-
|align="left" | '''access-list mode'''
|-
|align="left" | ['''no'''] '''failover suspend-config-sync'''
|-
|align="left" | ['''no'''] '''np''' ['''add''' | '''del''' | '''acl-notify'''] ''keywords''
|-
|align="left" | ['''no'''] '''np''' {['''1''' | '''2''' | '''3''' | '''all''']} ''keywords''
|-
|align="left" | ['''no'''] '''npcp''' ''keywords''
|-
|align="left" | '''upgrade-mp'''
|-
|}

Show Command Differences

2009-08-28T21:46:19Z

Lorlando: New page: =='''show''' Command Differences== The following table lists the '''show''' commands that are in FWSM software but not in ASA software. {| border="1" |- |align="left" | '''show asr''' |- ...

=='''show''' Command Differences==

The following table lists the '''show''' commands that are in FWSM software but not in ASA software.
{| border="1"
|-
|align="left" | '''show asr'''
|-
|align="left" | '''show bridge-group'''
|-
|align="left" | '''show conn up'''
|-
|align="left" | '''show cpu threshold'''
|-
|align="left" | '''show dispatch statistics'''
|-
|align="left" | '''show dispatch table'''
|-
|align="left" | '''show flashfs'''
|-
|align="left" | '''show ip bgp'''
|-
|align="left" | '''show nic'''
|-
|align="left" | '''show np''' ''1'' | ''2'' | ''3'' ''keywords''
|-
|align="left" | '''show np''' ''keyword''
|-
|align="left" | '''show npcp''' ''keywords''
|-
|align="left" | '''show pc conn'''
|-
|align="left" | '''show pc local-host'''
|-
|align="left" | '''show pcdebug'''
|-
|align="left" | '''show pc xlate'''
|-
|align="left" | '''show resource acl-partition'''
|-
|align="left" | '''show resource partition'''
|-
|align="left" | '''show resource rule'''
|-
|align="left" | '''show route-inject'''
|-
|align="left" | '''show route-monitor'''
|-
|align="left" | '''show running-config all control-point tcp-normalizer'''
|-
|align="left" | '''show running-config all ftp-map'''
|-
|align="left" | '''show running-config all grp-map'''
|-
|align="left" | '''show running-config all h225-map'''
|-
|align="left" | '''show running-config all mgcp-map'''
|-
|align="left" | '''show running-config all rip'''
|-
|align="left" | '''show running-config all route-inject'''
|-
|align="left" | '''show running-config all route-monitor'''
|-
|align="left" | '''show running-config all xlate-bypass'''
|-
|}

Clear Command Differences

2009-08-28T21:36:49Z

Lorlando: New page: =='''clear''' Command Differences== The following table lists the '''clear''' commands that are in FWSM software but not in ASA software. {| border="1" |- |align="left" | '''clear configur...

=='''clear''' Command Differences==
The following table lists the '''clear''' commands that are in FWSM software but not in ASA software.
{| border="1"
|-
|align="left" | '''clear configure ftp-map'''
|-
|align="left" | '''clear configure resource partition'''
|-
|align="left" | '''clear configure resource rule'''
|-

|-
|-
|align="left" | '''clear control-point tcp-normalizer'''
|-

|align="left" | '''clear dispatch stats all'''
|-
|align="left" | '''clear gtp-map'''
|-
|align="left" | '''clear h225-map'''
|-
|align="left" | '''clear ip bgp'''
|-
|align="left" | '''clear mgcp-map'''
|-
|align="left" | '''clear np''' ''1'' | ''2'' | ''3'' ''keyword''
|-
|align="left" | '''clear np all stats'''
|-
|align="left" | '''clear npcp statistics'''
|-
|align="left" | '''clear rip'''
|-
|align="left" | '''clear route-inject'''
|-
|align="left" | '''clear route-monitor'''
|-
|align="left" | '''clear route-monitor statistics'''
|-
|align="left" | '''clear route statistics'''
|-
|align="left" | '''clear router bgp'''
|-
|align="left" | '''clear xlate-bypass'''
|-
|}

Exec Command Differences

2009-08-28T21:26:27Z

Lorlando: New page: ==Exec Command Differences== The following table lists the '''debug''' commands that are in FWSM software but not in ASA software. {| border="1" |- |align="left" | ['''show''' | '''no'''] ...

==Exec Command Differences==
The following table lists the '''debug''' commands that are in FWSM software but not in ASA software.
{| border="1"
|-
|align="left" | ['''show''' | '''no'''] '''debug acl optimization'''
|-
|align="left" | ['''show''' | '''no'''] '''debug aging'''
|-
|align="left" | ['''show''' | '''no'''] '''debug control-plane'''
|-
|align="left" | ['''show''' | '''no'''] '''debug ip bgp'''
|-
|align="left" | ['''show''' | '''no'''] '''debug npcp'''
|-
|align="left" | ['''show''' | '''no'''] '''debug pc-lu'''
|-
|align="left" | ['''show''' | '''no'''] '''debug pisa'''
|-
|align="left" | ['''show''' | '''no'''] '''debug resource partition'''
|-
|align="left" | ['''show''' | '''no'''] '''debug route-inject'''
|-
|align="left" | ['''show''' | '''no'''] '''debug route-monitor'''
|-
|align="left" | ['''show''' | '''no'''] '''debug route-np'''
|-
|align="left" | ['''show''' | '''no'''] '''debug RM-NP-counter'''
|-
|align="left" | ['''show''' | '''no'''] '''debug session'''
|-
|align="left" | ['''show''' | '''no'''] '''debug ssl'''
|-
|}

Configuration Command Differences

2009-08-28T21:05:04Z

Lorlando: New page: The following table lists the differences among FWSM and ASA software configuration commands. {| border="1" cellpadding="2" !width="250" align="left" style="background:#99CCFF;" |'''Featur...

The following table lists the differences among FWSM and ASA software configuration commands.
{| border="1" cellpadding="2"
!width="250" align="left" style="background:#99CCFF;" |'''Feature/Command'''
!width="450" align="left" style="background:#99CCFF;" |'''FWSM Description'''
!width="250" align="left" style="background:#99CCFF;" |'''ASA Description'''
|-
|Connection timeouts for all protocols
'''set connection timeout idle'''
|The '''idle''' keyword was introduced in FWSM release 3.2(1). This command closes idle connections of all protocols after the specified period of time.
|The '''idle''' keyword is not supported in ASA software. The ASA software has the '''tcp''' keyword, which is used to close TCP comnections after a specified time.
|-
|Connection rate limit
'''set connection conn-rate-limit'''
|This command was introduced in FWSM release 4.0(1). It allows users to rate limit TCP and/or UDP connections to a value specified in the CLI.
|This command is not present in ASA software.
|-
|AAA authentication challenge
'''aaa authentication challenge disable'''
|This command was introduced in FWSM release 3.1(1). This command disables authentication challenge for ftp, telnet, http, and https.
|This command is not supported in ASA software.
|-
|AAA authentication clear conn
'''aaa authentication clear-conn'''
|This command was introduced in FWSM release 3.2(1). This command forces active connections to close immediately after user authentication times out or when the authentication session is cleared with the '''clear uauth''' command.
|This command is not supported in ASA software.
|-
|Virtual SSH
[no] '''virtual ssh'''
|This command was introduced in FWSM release 3.2(1). This command allows direct authentication using SSH.
|This command is not supported in ASA software.
|-
|Interactive password prompts with RADIUS for authentication
'''auth-prompt reject''' ['''invalid-credentials''' | '''expired-pwd''']
|This command was introduced in FWSM release 1.1. The '''invalid-credentials''' and '''expired-pwd''' options were added in FWSM release 3.2(1). This command, with the new options, allows users to specify the strings during authentication rejection sdue to invalid credentials or expired passwords.
|This command is suppored in ASA software, but the '''invalid-credentials''' and '''expired-pwd''' options are not supported.
|-
|DHCP relaty trusted interface (option 82)
'''dhcprelay information trusted'''
'''dhcprelay information trustedall'''
|This command was introduced in FWSM command 4.0. This command allows users to preserve option 82 and forward a packet by identifying an interface as a trusted interface, ensuring that DHCP snooping and IP source guard features on the switch work along with the FWSM. The '''trustall''' keyword enables the command for interfaces, as opposed to the '''trusted''' keyword, which enables the command for a single interface.
|This command is not supported in ASA software.
|-|
|http-map
'''port-misuse'''
|The command was introduced in FWSM release 3.1(1). This command restricts HTTP traffic by specifying a restricted application category. The '''port-misuse''' command is used in http map configuration mode, that is accessible using the '''http-map''' command.
|This command is not supported in ASA software.
|-
|'''logging deny conn-queue-full'''
|This command was introduced in FWSM release 3.1(1). When traffic is so heavy that the loggin gqueue fills up, the FWSM might discard messages. This command prevents the creation of new transit connections through the FWSM to avoid discarding messages.
|This command is not supported in ASA software.
|-
|CPU Threshold
[no] '''cpu threshold rising
|This command was introduced in FWSM release 3.2(1). When SNMP is enabled, traps are sent when the CPU levels reach a certain configurable mark.
|This command is not supported in ASA software.
|-
|EtherType Access Lists and denying IPv4 and ARPs
|In TFW mode with an ethertype access list configured to "deny all," both IPv4 and ARP cannot be denied on a FWSM device.
|In TFW mode with an ethertype access list configured to "deny all," all ethertypes are denied, including IPv4 and ARP.
|-
|Direct Login or Logout using Virtual HTTP for User Authentication
'''virtual http ip_address''' ['''host''' ''hostname'']
|Direct authentication including login and logout are supported using the '''virtual http''' command.
|ASA software supports the login aspect of direct authentication but not logout. Because logout is not support, direct authentication is not supported. ASA software does support cascading authentication with the '''virtual http''' command.
|-
|Route Monitoring
'''route-monitor'''
|The route-monitoring feature is supported. If multiple static routes are configured, the feature can detect if a network goes down and the next best route is used.
|This feature is supported in ASA software using the '''sla monitor''' command. In this feature the ASA software supports more commmand options than FWSM software.
|-
|Old maps for inspections
[no] '''ftp-map'''

[no] '''gtppmap'''

[no] '''h225-map'''

[no] '''http-map'''

[no] '''mgcp-map'''

[no] '''sip-map'''

[no] '''snmp-map'''

|FWSM software still supports the old style xxx-map commands.
|ASA software converted to the new style '''policy-map''' and ''policy-match''' commands in release 7.2.
|-
|RIP
'''rip'''
|FWSM software still suppports the old style single line '''rip''' configuration command.
|ASA software converted to the new style multiline '''rip''' configuration command in release 7.2
|-
|TCP normalizer knob
[no] '''control-point tcp-normalizer'''
|FWSM software supports a limited TCP normalizer. This feature can be turned on or off using a knob.
|ASA software does not have a nob to turn off the TCP normalizer.
|-
|Rate limits
'''access-list-commit'''

'''allocate-acl-partition'''

'''size'''

[no] '''resource acl-partition'''

[no] '''resource partition'''

[no] '''resource rule'''

'''rule'''

|Due to Hard NPs, FWSM has fixed rule limits and many commands to handle the limits.
|ASA software does not have fixed rate limits, so it does not have these commands.
|-
|Xlates for all traffic
[no] '''xlate-bypass'''
|FWSM software always creates xlates for all traffic, including to-the-box traffic. This command was introduced to work around the xlate creation.
|ASA software does not create xlates for all traffic, so it does not have these commands.
|-
|ACL optimization
[no] '''access-list optimization enable'''
|This command enables the access list optimization rules, which are optimized and downloaded to the Hard NPs. The command also reduces the number of ACEs for for each group.
|This command is not supported in ASA software.
|-
|'''syspot uauth allow-http-cache'''
|This command is related to the direct authentication part of the '''virtual http''' command. When an authentication sessions times out and when a user connects again without this command, the username and password are prompted again. If this command is used, then the web browser is allowed to supply the username and password from its cache.
|This command is not present in ASA software.
|-
|'''sysopt np completion-unit'''
|This command was introduced in FWSM release 3.2(5). This command allows users to enable the hardware completion unit in the accelerated path network processors (NPs), which ensures that packets are forwarded out in the same order in which they were received in the ingress queues of the NPs.
|This command is not present in ASA software.
|-
|'''sysopt connection tcp sack-permitted'''
|This command was introduced in FWSM release 3.1(12). The '''no''' form of the command allows users to clear the '''sack permitted''' option exchanged during the TCP three-way handshake. The '''sack''' option is enabled by default.
|This command is implemented using the '''tcp-options selective-ack clear''' / '''allow''' command under tcp-map. The default is to allow the '''sack''' option, as done in FWSM.
|-
|'''sysopt connection tcp window-scale'''
|This command was introduced in FWSM release 3.1. Thi '''no''' form of the command allows users to clear the window-scale TCP option. The option is allowed by default.
|This command is implemented using the '''tcp-options window-scale''' {'''clear''' / '''allow'''} command under tcp-map. The default is to allow the window-scale option, as done in FWSM.
|-
|Disaster Recovery
'''boot device module''' ''slot string''
|This is a SUP command that allows for disaster recovery of FWSM software by specifying different compact flash partitions.
|In ASA software disaster recovery is performed using ROMMOM and a console connection.
|-
|SNMP trap commands
'''snmp-server enable traps cpu threshold'''

'''snmp-server enable traps cpu threshold rising'''

'''snmp-server enable traps entity redun-switchover'''

'''snmp-server enable traps entity alarm-asserted'''

'''snmp-server enable traps entity alarm-cleared'''

'''snmp-server enable traps nat'''

'''snmp-server enable traps nat packet-discard'''

'''snmp-server enable traps rate-limit-reached'''

'''snmp-server enable traps resource'''

'''snmp-server enable traps resource limit-reached'''
|These commands and the related traps were introduced in FWSM release 3.2(1).
|These commands and the related traps are not supported in ASA software.
|-
|Service Reset
[no] '''service reset no-connection'''
|This command was introduced in FWSM release 4.0. This command configures the FWSM to send a RST for a TCP packet, for which the FWSM does not have any connection history.
|ASA software achieves the same behavior using the '''service resetinbound''' command.
|-
|[no] '''aaa schedule round-robin'''
|This command has no documentation, although it appears to have been introduced in FWSM release 3.1 to resolve an AAA bug, which states the following: "The problem is, we see a lot of stale https connections on tehe groupq, which is not allowing the other connections like telnet and ftp to pass though. This will result in a latency in echoing back the characters typed on the telnet client. To get away from this problem, we are crating a cli '''aaa schedule round-robin''' which will schedule the groupq and allow other connections to be processed smoothly, if there are any stale https connections. Use the no form of this command to make the groupq to be processed in fifo format (which is the default)."
|This command is not present in ASA software.
|-
|Resource limits
'''limit-resource ipsec''' ''value / value%''

'''limit-resource mac-addresses''' ''value / value%''

'''limit-resource rate fixips''' ''value''

'''limit-resource rate''' ''resource value%''

|The '''limit resource''' command supports rate limit % as the resources have upper limits. It also supports limiting MAC addresses and IPSec management tunnels.
| ASA software does not have upper limits on resources, so it does not support % rate limits for resources. ASA software also does not support limiting MAC addresses and IPSec tunnels.
|-
|URL-Server
'''url-server''' ''ifc name'' ''' vendor websense host local_ip protocol tcp connections num_conns'''

'''url-server''' / ''ifc name'' '''vendor websense host local_ip protocol udp context-name'''

|In FWSM release 4.0 in multipmode context name, this command can be sent to the websense server using the '''context-name''' keyword. Also, the '''connections''' keyword can be used to specify the number of simultaneous TCP connections without the '''protocol''' keyword.
|ASA software does not support the '''context-name''' keyword. Also, it requires the '''protocol''' keyword, followed by TCP for configuring the number of simultaneous connections.
|-
|}

Feature Differences

2009-08-28T21:02:25Z

Lorlando:

==Feature Differences==
The following table lists the feature differences between FWSM and ASA.
{| border="1" cellpadding="2"
!width="250" align="left" style="background:#99CCFF;" |'''Feature'''
!width="450" align="left" style="background:#99CCFF;" |'''FWSM Description'''
!width="250" align="left" style="background:#99CCFF;" |'''ASA Description'''
|-
|Authentication support when sessioning to system context in multiple mode
'''aaa authentication telnet console''' command from admin context
|In multi mode AAA commands cannot be configured in system context. However, telenet authenication in admin context is used for authenticating sessions from the supervisor engines that enter system context.
|Does not have session command support, so AAA authentication in the admin context is not used by the system context.
|-
|IPSec in multimode
(managment only)
|IPSec is supported for management purposed in multimode.
|No IPSec support in multimode.
|-
|Mixed mode support
CLI:
'''firewall transparent'''
|This is a feature in FWSM in which the firewall mode can be set in each context in multimode.
|Not supported in ASA, and the firewall mode is set for the entire device.
|-
|Bridge Groups
CLI:
'''bridge-group interface bvi'''
|This feature in FWSM increased the number of interfaces in transparent mode to eight pairs from a single pair.
|Not supported in ASA.
|-
|Asymmetric Routing
(non active/active mode)
|When asymmetic routing was introduced in FWSM, the active/active restriction that is present in ASA was removed.
|Supported in active/active mode only.
|-
|BGP Stub Routing
CLI:
'''router bgp'''
'''bgp router-id'''
'''neighbor remote-as'''
'''neighbor password'''
'''network'''
|Supported in FWSM.
|Not supported in ASA.
|-
|Failover preemption for active/standby failover
|FWSM can be configured in an active/standby scenario. When configured, the primary unit always becomes active after a certain time in the following cases:
1. When the primary unit fails and the secondary unit becomes active.

2. When the secondary unit boots before the primary unit, and the secondary unit becomes active.
|Not supported in ASA.
|-
|Trusted Flow Acceleration
CLI:
'''service-acceleration'''
'''set connect'''
'''advanced options'''
|This feature lets the FWSM take advantage of the processing power of the switch supervisor engine that allows for increased throughput by installing EARL shortcuts.
|Not supported in ASA.
|-
|Route Health Inspection
CLI:
'''route-inject'''
'''redistribute nat'''
'''redistribute connected'''
'''redistribute static'''
|This feature installs connected, static, NAT pool routes configured on the FWSM into MSFC on a per-contxt basis. MSFC can then redistribute the routes.
|Not supported in ASA.
|-
|PISA Integration
CLI:
'''permit'''
'''deny'''
|The FWSM uses this feature to leverage the high-performance deep packet inspection of the PISA card so that it can permit or deny traffic based on the application type.
|Not supported in ASA.
|-
|DHCP Relay interface specific servers
CLI:
'''interface vlan''' <''vlan id''>
'''dhcprelay server''' <''ip_address''>
|This feature is Uauth for FWSM.
|-
|Stateful Failover Uath Table Replication
|FWSM supports replicating Uauth Table in the failover peer when stateful failover is configured.
|Not supported in ASA.
|}

Feature Differences

2009-08-28T20:48:07Z

Lorlando: New page: ==Feature Differences== The following table lists the implicit behavioral differences between FWSM and ASA. {| border="1" cellpadding="2" !width="250" align="left" style="background:#99CCF...

==Feature Differences==
The following table lists the implicit behavioral differences between FWSM and ASA.
{| border="1" cellpadding="2"
!width="250" align="left" style="background:#99CCFF;" |'''Feature'''
!width="450" align="left" style="background:#99CCFF;" |'''FWSM Description'''
!width="250" align="left" style="background:#99CCFF;" |'''ASA Description'''
|-
|Authentication support when sessioning to system context in multiple mode
'''aaa authentication telnet console''' command from admin context
|In multi mode AAA commands cannot be configured in system context. However, telenet authenication in admin context is used for authenticating sessions from the supervisor engines that enter system context.
|Does not have session command support, so AAA authentication in the admin context is not used by the system context.
|-
|IPSec in multimode
(managment only)
|IPSec is supported for management purposed in multimode.
|No IPSec support in multimode.
|-
|Mixed mode support
CLI:
'''firewall transparent'''
|This is a feature in FWSM in which the firewall mode can be set in each context in multimode.
|Not supported in ASA, and the firewall mode is set for the entire device.
|-
|Bridge Groups
CLI:
'''bridge-group interface bvi'''
|This feature in FWSM increased the number of interfaces in transparent mode to eight pairs from a single pair.
|Not supported in ASA.
|-
|Asymmetric Routing
(non active/active mode)
|When asymmetic routing was introduced in FWSM, the active/active restriction that is present in ASA was removed.
|Supported in active/active mode only.
|-
|BGP Stub Routing
CLI:
'''router bgp'''
'''bgp router-id'''
'''neighbor remote-as'''
'''neighbor password'''
'''network'''
|Supported in FWSM.
|Not supported in ASA.
|-
|Failover preemption for active/standby failover
|FWSM can be configured in an active/standby scenario. When configured, the primary unit always becomes active after a certain time in the following cases:
1. When the primary unit fails and the secondary unit becomes active.

2. When the secondary unit boots before the primary unit, and the secondary unit becomes active.
|Not supported in ASA.
|-
|Trusted Flow Acceleration
CLI:
'''service-acceleration'''
'''set connect'''
'''advanced options'''
|This feature lets the FWSM take advantage of the processing power of the switch supervisor engine that allows for increased throughput by installing EARL shortcuts.
|Not supported in ASA.
|-
|Route Health Inspection
CLI:
'''route-inject'''
'''redistribute nat'''
'''redistribute connected'''
'''redistribute static'''
|This feature installs connected, static, NAT pool routes configured on the FWSM into MSFC on a per-contxt basis. MSFC can then redistribute the routes.
|Not supported in ASA.
|-
|PISA Integration
CLI:
'''permit'''
'''deny'''
|The FWSM uses this feature to leverage the high-performance deep packet inspection of the PISA card so that it can permit or deny traffic based on the application type.
|Not supported in ASA.
|-
|DHCP Relay interface specific servers
CLI:
'''interface vlan''' <''vlan id''>
'''dhcprelay server''' <''ip_address''>
|This feature is Uauth for FWSM.
|-
|Stateful Failover Uath Table Replication
|FWSM supports replicating Uauth Table in the failover peer when stateful failover is configured.
|Not supported in ASA.
|}

Implicit Behavioral Differences

2009-08-28T20:44:19Z

Lorlando:

==Implicit Behavioral Differences==
The following table lists the implicit behavioral differences between FWSM and ASA.
{| border="1" cellpadding="2"
!width="250" align="left" style="background:#99CCFF;" |'''Implicit Behavior'''
!width="450" align="left" style="background:#99CCFF;" |'''Behavior in FWSM'''
!width="250" align="left" style="background:#99CCFF;" |'''Behavior in ASA'''
|-
| Implicit Deny
| Implicit deny between all interfaces.
| Implicit permit from high security to low security interfaces.
|-
| ICMP to-the-box deny
| Implicit ICMP deny to the interface.
| Implicit permit.
|-
| NAT matching for statistics
| Static NAT and static PAT (regular and policy '''static''' command) -- Best Match. In the case of overlapping address in the static statements, a warning is displayed, but they are supported. The order of static commands does not matter; the static statement that best matches the real address is used.
| Static NAT and static PAT (regular and policy '''static''' command) -- In order until the first match.
|-
|}

Implicit Behavioral Differences

2009-08-28T20:34:04Z

Lorlando: New page: ==Implicit Behavioral Differences== The following table lists the implicit behavioral differences between FWSM and ASA. {| class="wikitable" |- !'''Implicit Behavior''' !'''Behavior in FW...

==Implicit Behavioral Differences==
The following table lists the implicit behavioral differences between FWSM and ASA.
{| class="wikitable"
|-
!'''Implicit Behavior'''
!'''Behavior in FWSM'''
!'''Behavior in ASA'''
|-
| Implicit Deny
| Implicit deny between all interfaces.
| Implicit permit from high security to low security interfaces.
|-
| ICMP to-the-box deny
| Implicit ICMP deny to the interface.
| Implicit permit.
|-
| NAT matching for statistics
| Static NAT and static PAT (regular and policy '''static''' command) -- Best Match. In the case of overlapping address in the static statements, a warning is displayed, but they are supported. The order of static commands does not matter; the static statement that best matches the real address is used.
| Static NAT and static PAT (regular and policy '''static''' command) -- In order until the first match.
|-
|}

Migrating from Cisco FWSM to Cisco ASA Software

2009-08-28T20:32:48Z

Lorlando: New page: This document outlines the differences between Cisco FWSM 4.0(1) and Cisco ASA 8.2(1) software to provide users with information to use when making the decision to migrate from FWSM to ASA...

This document outlines the differences between Cisco FWSM 4.0(1) and Cisco ASA 8.2(1) software to provide users with information to use when making the decision to migrate from FWSM to ASA software. Features that are in FWSM but not in ASA are described, as well as features that are available on both platforms but are implemented differently. Features that are in ASA but are not available in FWSM are not listed.

This wiki includes the following sections:
* [[Implicit Behavioral Differences]]
* [[Feature Differences]]
* [[Configuration Command Differences]]
* [[Exec Command Differences]]
* [[clear Command Differences]]
* [[show Command Differences]]
* [[Exec and Unsaved Config Command Differences]]
* [[Default Value and Value Range Differences]]
* [[SNMP Differences]]
* [[System Log Message Differences]]

Main Page

2009-08-28T19:39:38Z

Lorlando:

<big>'''Welcome to DocWiki'''</big>

DocWiki is a cross-functional trial of the use of wiki technology to improve collaboration with our customers on Cisco documentation.

If this is your first visit to DocWiki, please carefully read the [[DocWiki:Terms_of_use|Terms of Use]]. For more information about the way this wiki operates, refer to the [[DocWiki:About|About DocWiki]] pages.

To edit or add content to documentation, select the "edit" tab on the appropriate article page. To submit questions or comments about documentation content, select the "discussion" tab. To send feedback about DocWiki to the team, contact [mailto:docwiki-support@cisco.com docwiki-support@cisco.com].

During this trial phase, the scope of product documentation being offered on DocWiki is limited. If you have other technical documentation you would like to post to DocWiki, please contact [mailto:docwiki-support@cisco.com docwiki-support@cisco.com].

==Finding Articles on DocWiki==

Use the topic map below to find articles on DocWiki. You can also use the search box on the left.

{|style="width:100%; background-color: #EEEEEE; color: #fff; border:none;"
|-
| style="width:20%;" |<center>
{{navimg|xsize=40|ysize=40|image=router.gif|link=Category:Cisco Products}}
</center>
| style="width:20%;" |<center>
{{navimg|xsize=40|ysize=40|image=topology.gif|link=Category:Technologies}}
</center>
| style="width:20%;" |<center>
{{navimg|xsize=40|ysize=40|image=systems.gif|link=Category:Systems}}
</center>
| style="width:20%;" |<center>
{{navimg|xsize=40|ysize=40|image=tools.gif|link=Category:Configuration Examples}}
</center>

|-
|<center>'''[[:Category:Cisco Products|Cisco Products]]'''</center>
|<center>'''[[:Category:Technologies|Technologies]]'''</center>
|<center>'''[[:Category:Systems|Systems]]'''</center>
|<center>'''[[:Category:Configuration Examples|Configuration Examples]]'''</center>
|}

See the [[Special:Categories|Categories list]] to browse all categories.

== Documentation ==

[[Cisco Application Control Engine (ACE)]]

[[Using_Cisco_Emergency_Responder|Cisco Emergency Responder]]

[[Cisco IOS Voice Troubleshooting and Monitoring Guide]]

[[Cisco Nexus Switches]]

[[Cisco Optical Networking]]

[[Cisco Unified Communications]]

[[Cisco Unified MeetingPlace, Release 7.0]]

[[Cisco Unified MeetingPlace, Release 6.x]]

[[Cisco Unified MeetingPlace Express, Release 2.x]]

[[Cisco Unified Presence, Release 7.x|Cisco Unified Presence Releases 7.0, 7.0(2), 7.0(3) and 7.0(4)]]

[[Cisco_WAAS_4.1.1_--_Cisco_Wide_Area_Application_Services_Quick_Configuration_Guide|Cisco Wide Area Application Services Quick Configuration Guide, Release 4.1.1]]

[[Fabric Analysis and Correlation Toolkit User Guide]]

[[Internetwork Design Guide|Internetworking Design Guide]]

[[Internetworking Technology Handbook]]

[[Migrating from Cisco FWSM to Cisco ASA Software]]

[[:Category:Unified_Expert_Advisor%2C_Release_7.6%281%29|Troubleshooting Tips for Unified Expert Advisor, Release 7.6(1)]]

[[Unified Expert Advisor Documentation Set, Release 7.6(1)]]

Obtaining and Installing FACT

2008-06-12T18:24:07Z

Lorlando: /* Obtaining the FACT RPM File */

==Obtaining the FACT RPM File==

FACT is distributed as an RPM file. To obtain a copy of the FACT RPM, perform the following steps:

'''Step 1''' Navigate to the Cisco software download site at the following URL:
::http://www.cisco.com/kobayashi/sw-center/index.shtml
::If you are not already a registered user, you must register at the preceding URL to gain access to software downloads.

'''Step 2''' Select the software product category by clicking the '''Server Network and Virtualization''' link.

'''Step 3''' Select a device by choosing '''Server Fabric Software''' > '''InfiniBand Management Software''' > '''Cisco Fabric Analysis and Correlation Toolkit'''.

==Installing FACT Software==

To install the RPM, perform the following steps:

'''Step 1''' Log in as a super user.

'''Step 2''' Install the FACT RPM by entering the following command:
::'''# rpm -i cisco-fact-''' ''version'' '''-noarch.rpm'''
::After FACT installs you can obtain and install additional software to make use of the full FACT functionality. (See [[Obtaining and Installing FACT#Obtaining and Installing Optional Software Tools|Obtaining and Installing Optional Software Tools]].) Otherwise, you must create the FACT configuration files.

==Obtaining and Installing ibspark==
FACT enables users to upgrade firmware on unmanaged switches and on the control ports. To control the ports you must have the ibportstate utility available on a host with which FACT can communicate, and to upgrade firmware on unmanaged switches you must obtain and install the ibspark tool.

'''Note''': To control the ports you must have the ibportstate utility available on a host with which FACT can communicate. The ibportstate utility is an Open Fabrics utility that is not included with FACT software.

To obtain and install the optional ibspark software tool, perform the following steps:

'''Step 1''' Navigate to the Cisco software download site at the following URL:
::http://www.cisco.com/kobayashi/sw-center/index.shtml
::If you are not already a resitered user, you must register at the preceding URL to gain access to sofware downloads.

'''Step 2''' Select the software product category by clicking the '''Server Network and Virtualization''' link.

'''Step 3''' Select the ibspark tool by choosing '''Server Fabric Software''' > '''InfiniBand Management Software''' > '''Cisco Fabric Analysis and Correlation Toolkit''' > '''ibspark'''.

'''Step 4''' Install ibspark.

[[Category:Installing Software]]

FACT Quick Start Guide

2008-06-12T18:22:29Z

Lorlando: /* Obtaining FACT Software */

This section includes the minimal tasks involved in installing and configuring FACT. For details about these installation and configuration tasks, see [[Obtaining and Installing FACT|Obtaining and Installing FACT]] and [[Creating FACT Configuration Files|Creating FACT Configuration Files]].

= Obtaining and Installing FACT Software =
Before you obtain and install FACT, ensure that you are running the following software on your system: RedHat Enterprise Linux, Version 4 or 5, or SUSE Linux Enterprise Distribution, Version 9 or 10, and Python, Version 2.3 or later.

==Obtaining FACT Software==
FACT is distributed as an RPM file. To obtain a copy of the FACT RPM, perform the following steps:

'''Step 1''' Navigate to the Cisco software download site at the following URL: http://www.cisco.com/kobayashi/sw-center/index.shtml

::If you are not already a registered user, you must register at the above URL to gain access to software downloads.

'''Step 2''' Select the software product category by clicking the '''Server Network and Virtualization''' link.

'''Step 3''' Select a device by choosing '''Server Fabric Software > InfiniBand Management Software > Cisco Fabric Analysis and Correlation Toolkit'''.

==Installing FACT Software==

To install the FACT software RPM, perform the following steps:

'''Step 1''' Log in to your console as a super user.

'''Step 2''' Install the RPM by entering the following command:

::'''rpm -i cisco-fact-''' ''version'' '''.noarch.rpm'''
'''Step 3''' FACT installs the software without status messages. To verify that you have installed the correct version of FACT, enter the '''fact -v''' command, and verify the version number in the command output.

=Configuring FACT Software=
To configure FACT software you must create the master configuration file and create the credentials file.

==Creating the Master Configuration File==
For more information about master configuration files, see [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files.]]
To create the master configuration file, perform the following steps:

'''Step 1''' Log in to your host as a super user.

'''Step 2''' Using a text editor, create a master configuration file names .fact.conf in your home directory.

'''Step 3''' Enter the following line into the configuration file:
::'''credential-file: ~/.fact-credentials'''

'''Step 4''' For each managed switch that is running SFS OS in your network, add a line to the master configuration file that specifies the hostname or IP address:
::'''managed-nodes: SFSOS switch''' ''name''

::For information about managed nodes, see [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].

'''Step 5''' For each managed OEM switch that is in your network (either a Cisco SFS 7012 or Cisco SFS 7024), add a line to the file that specifies the hostname or IP address:
::'''managed-nodes: OEM switch''' ''name''

'''Step 6''' If you are using the High-Performance Subnet Manager, specify each host that runs the High-Performance Subnet Manager in the master configuration file:
::'''managed-nodes: host''' ''name''

'''Step 7''' (Optional) FACT usually determines the names of hosts on the network without needing to log in to them. If FACT does not identify the hosts or if you want FACT to collect additional diagnostic information from the hosts, add each host in your network to the master configuration file:
::managed-nodes: host ''' ''name''

'''Step 8''' (Optional) If you have unmanaged switches in your network, add a line to the master configuration file that specifies the GUID name and creates a name for the switch. (For more information about GUID names, see [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].) You may use any name for the switch, but you must use the following format for the line that you add to the file:
::guid-name: 00:1b:0d:00:00:ca:a6 switchA
::guid-name: 00:1b:0d:00:00:ca:aa switchB

==Creating the Credentials File==
For more information about the credentials file, see [[About FACT Configuration Files#About Credentials Files|About Credentials Files.]]
To create a credentials file, perform the following steps:

'''Step 1''' Using a text editor, create a file named .fact-credentials in your home directory.

'''Step 2''' For each managed node (switch or host) that you listed in the master configuration file, add a username and a password that FACT can use to log in to that managed node. Choose Case 1 or Case 2 from the following steps:

::'''Case 1'''--If each switch or host in your network has a different username or password, create a separate stanza in the credentials file for each switch and each host, as shown in the following example:
:::SFSOS switch ''name''
::::user: ''username''
::::password: ''password''

:::OEM switch ''name''
::::host myhost[1-8]
::::user: ''username''
::::password: ''password''

:::host ''name''
::::user: ''username''
::::password: ''password''

::'''Case 2'''--If all managed nodes of a given type (host, SFS OS switch, or OEM switch) have the same username and password, create one stanza for each node type, as shown in the following examples:

:::SFSOS switch *
::::user: ''username''
::::password: ''password''

:::OEM switch *
::::user: ''username''
::::password: ''password''

:::host *
::::user: ''username''
::::password: ''password''

'''Step 3''' Save the credentials file that you just created.

'''Step 4''' Verify the configuration by entering the '''fact scan fabric''' command, which scans the managed nodes in the master configuration file.

'''Step 5''' If FACT reports errors while scanning, see [[FACT Quick Start Guide#Troubleshooting FACT Configuration|Troubleshooting FACT Configuration]].

=Troubleshooting FACT Configuration=

If FACT reports errors while scanning, consult this section for common symptoms, possible causes, and recommended actions.

'''Symptom''': FACT returns an error message indicating that permission is denied: <code>"name: permission denied."</code>

:'''Possible cause''': The credentials file is either missing or incorrect.

:'''Recommended action''': Correct the credentials file. (See [[Creating FACT Configuration Files#Creating the Credentials File|Creating the Credentials File]].)

'''Symptom''': FACT returns a time-out message: <code>"ScanError: timeout scanning name."</code>

:'''Possible cause''': The master configuration file has an incorrect host name or IP address, or the host is not reachable using the name that appears in the file.

:'''Recommended action''': Verify that you have entered the correct host name or IP address in the master configuration file. (See [[Creating FACT Configuration Files#Creating the Master Configuration File|Creating the Master Configuration File]].) Also, verify that the managed node is reachable through SSH.

'''Symptom''': When you attempt to scan the network, FACT returns a message saying that multiple master Subnet Managers are found: <code>"ScanError: multiple Master Subnet Managers found."</code>

:'''Possible cause''': The master configuration file contains managed nodes from multiple subnets. FACT can scan a single subnet only.

:'''Recommended action''': Enter the FACT '''show subnet-managers''' command to see all of the master and standby Subnet Managers that FACT found. From the master configuration file and from the credentials file, remove the Subnet Managers that are not in the subnet that you are scanning.

'''Symptom''': FACT cannot find a master Subnet Manager: <code>"ScanError: no Master Subnet Manager found."</code>

:'''Possible cause''': The node that is running the master Subnet Manager is not in the master configuration file. (See [[Creating FACT Configuration Files#Creating the Master Configuration File|Creating the Master Configuration File]].)

:'''Recommended action''': Check the master configuration file, and add the node that is running the master Subnet Manager if it does not exist in the file.

FACT Quick Start Guide

2008-06-12T18:22:10Z

Lorlando: /* Obtaining FACT Software */

FACT show routes

2008-06-12T18:19:34Z

Lorlando:

To show the unicast routes from each port in the source set to each port in the destination set, use the '''show routes''' command.

::::::'''show routes''' [chassis | chip] {from [''src-hosts'' | ''src-switches'' | ''src-ports'']} {to [''dst-hosts'' | ''dst-switches'' | ''dst-ports'']} [guids]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Show a chassis-level view of each route.
|-
|chip
|(Optional) Show a chip-level view of each route.
|-
|from
|Indicates from which port the route originates.
|-
|''src-hosts''
|(Optional) Identifies the hosts from the source set.
|-
|''src-switches''
|(Optional) Identifies the switches from the source set.
|-
|''src-ports''
|(Optional) Identifies the ports from the source set.
|-
|to
|Identfies the destination set.
|-
|''dst-hosts''
|(Optional) Identfies the hosts in the destination set.
|-
|''dst-switches''
|(Optional) Identfies the switches in the destination set.
|-
|''dst-ports''
|(Optional) Identfies the ports in the destination set.
|-
|guids
|(Optional) Shows device GUIDs.
|}

'''Command Default'''
::::::If the '''chassis''' or '''chip''' are not specified, the default view is the chassis-level view.
::::::If the source or the destination is not specified, then the default is to view the routes from all sources to all destinations.

'''Examples'''
::::::The following example shows the chassis view of all the routes from switchA to host01. Each route has two hops. SwitchA has three switch chips, and port 0 on each switch chip is a source.
fact> '''show routes from switchA to host01'''

Route switchA/1:1/0 to host01/1/1, LID 792:
hop chassis ingress-port egress-port
--- ----------------------- ------------ -----------
1 switchA 1:1/0 1/3
2 switchB 1/3 1/7

Route switchA/1:2/0 to host01/1/1, LID 792:
hop chassis ingress-port egress-port
--- ----------------------- ------------ -----------
1 switchA 1:2/0 1/3
2 switchB 1/3 1/7

Route switchA/1:3/0 to host01/1/1, LID 792:
hop chassis ingress-port egress-port
--- ----------------------- ------------ -----------
1 switchA 1:3/0 1/3
2 switchB 1/3 1/7

::::::The following example shows the chip view of all the routes from switchA to host01. SwitchA has three switch chips, and port 0 on each switch chip is a source. Packets from switchA/1:1/0 and switchA/1:3/0 route through chip switchA/1:2.

fact> '''show routes chip from switchA to host01'''

Route switchA/1:1/0 to host01/1/1, LID 792:
hop chip ingress-port egress-port
--- ---------------------------- ------------ -----------
1 switchA/1:1 0 4
2 switchA/1:2 1 8
3 switchB/1:1 3 7

Route switchA/1:2/0 to host01/1/1, LID 792:
hop chip ingress-port egress-port
--- ---------------------------- ------------ -----------
1 switchA/1:2 0 8
2 switchB/1:1 3 7

Route switchA/1:3/0 to host01/1/1, LID 792:
hop chip ingress-port egress-port
--- ---------------------------- ------------ -----------
1 switchA/1:3 0 1
2 switchA/1:2 3 8
3 switchB/1:1 3 7

'''Related Commands'''
::::::[[FACT show destinations|'''show destinations''']]
::::::[[FACT show egress ports|'''show egress ports''']]
::::::[[FACT show multicast destinations|'''show multicast destinations''']]
::::::[[FACT show multicast egress ports|'''show multicast egress ports''']]
::::::[[FACT show multicast routes|'''show multicast routes''']]

FACT show multicast routes

2008-06-12T18:19:16Z

Lorlando:

To show multicast routes from each port in the source set to each port in the destination set, use the '''show multicast routes''' command.

::::::'''show multicast routes''' [chassis | chip] [{from ''src-hosts'' | ''src-switches'' | ''src-ports''}] [{'''to''' ''dst-hosts'' | ''dst-switches'' | ''dst-ports''}] [''multicast-groups''] [''guids'']

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Shows a chassis-level view of each route.
|-
|chip
|(Optional) Shows a chip-level view of each route.
|-
|from
|(Optional) Identifies the source set.
|-
|''src-hosts''
|(Optional) Shows only the routes from the specified source host ports.
|-
|''src-switches''
|(Optional) Shows only the routes from the specified source switch ports.
|-
|''src-ports''
|(Optional) Shows only the routes from the specified source ports.
|-
|to
|(Optional) Shows only those routes to the specified destinations.
|-
|''dst-hosts''
|(Optional) Shows only the routes to the specified destination host ports.
|-
|''dst-switches''
|(Optional) Shows only the routes to the specified destination switch ports.
|-
|''dst-ports''
|(Optional) Shows only the routes to the specified destination ports.
|-
|''multicast-groups''
|(Optional) Shows only the routes for the specified multicast groups.
|-
|''guids''
|(Optional) Shows the GUIDs for each hop on the route.
|}

'''Command Default'''
::::::The default view is the chassis view.

'''Examples'''
::::::The following is sample output from the '''show multicast routes''' command, and it shows the multicast routes from host01 to host02. It shows two multicast groups routed through different ports between switchA and switchB:
fact> '''show multicast routes from host01 to host02'''

Route host01/1/1 to host02/1/1,
MGID ff:18:a0:1b:00:00:00:00:00:00:05:ad:00:02:80:da, MLID 49152:
hop chassis ingress-port egress-port
--- -------------------- ------------ -----------
1 switchA 1/1 1/16
2 switchB 1/22 1/1

Route host01/1/1 to host02/1/1,
MGID ff:18:a0:1b:00:00:00:00:00:00:05:ad:00:02:80:db, MLID 49153:
hop chassis ingress-port egress-port
--- -------------------- ------------ -----------
1 switchA 1/1 1/14
2 switchB 1/24 1/1

'''Related Commands'''
::::::[[FACT show destinations|'''show destinations''']]
::::::[[FACT show egress ports|'''show egress ports''']]
::::::[[FACT show multicast destinations|'''show multicast destinations''']]
::::::[[FACT show multicast egress ports|'''show multicast egress ports''']]
::::::[[FACT show routes|'''show routes''']]

FACT show multicast egress ports

2008-06-12T18:18:57Z

Lorlando:

To show the egress ports that forward multicast traffic to each specified destination port, use the '''show multicast egress ports''' command.

::::::'''show multicast egress ports''' [chassis | chip] [to ''multicast-groups''] [guids]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Shows only switch chassis egress ports.
|-
|chip
|(Optional) Shows only the egress ports for each InfiniBand switch chip.
|-
|to
|(Optional) Identifies the destination set.
|-
|''multicast-groups''
|(Optional) Shows only the egress ports to the specified multicast groups.
|-
|guids
|(Optional) Shows device GUIDs.
|}

'''Command Default'''
::::::The default view is the chassis view. If ''multicast-groups'' is not specified, egress ports for all multicast destinations are shown.

'''Examples'''
::::::The following is sample output from the '''show multicast egress ports''' command, and it shows the egress ports used for each multicast group:
fact> '''show multicast egress ports'''

MGID ff:12:40:1b:ff:ff:00:00:00:00:00:00:00:00:00:01, lid 49153:
egress-port
--------------------------------
switchB/1/7

MGID ff:12:40:1b:ff:ff:00:00:00:00:00:00:ff:ff:ff:ff, lid 49152:
egress-port
--------------------------------
switchB/1/7

MGID ff:18:a0:1b:00:00:00:00:00:00:05:ad:00:02:80:da, lid 49154:
none found

'''Related Commands'''
::::::[[FACT show destinations|'''show destinations''']]
::::::[[FACT show egress ports|'''show egress ports''']]
::::::[[FACT show multicast destinations|'''show multicast destinations''']]
::::::[[FACT show multicast routes|'''show multicast routes''']]
::::::[[FACT show routes|'''show routes''']]

FACT show multicast destinations

2008-06-12T18:18:41Z

Lorlando:

To show the multicast destinations that are forwarded through each specified egress port, use the '''show multicast destinations''' command.

::::::'''show multicast destinations''' [''switches'' | ''ports''] [to ''multicast-groups'']

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|''switches''
|(Optional) Shows only the destinations from the specified switch ports.
|-
|''ports''
|(Optional) Shows only the destinations from the specified ports.
|-
|to
|(Optional) Identifies the destination multicast group set.
|-
|''multicast-groups''
|(Optional) Shows only the destinations for the specified multicast groups.
|}

'''Command Default'''
::::::If no port is specified, the default view is the port view. If ''multicast-groups'' is not specified, all multicast destinations forwarded through each specified egress ports are shown.

'''Examples'''
::::::The followingis sample output from the '''show multicast destinations''' command, and it shows all multicast destinations that egress chip switchB/1:1 through port 7:
fact> '''show multicast destinations switchB/1:1/7'''

Egress port switchB/1/7:
mgid mlid
----------------------------------------------- -----
ff:12:40:1b:ff:ff:00:00:00:00:00:00:ff:ff:ff:ff 49152
ff:12:40:1b:ff:ff:00:00:00:00:00:00:00:00:00:01 49153

'''Related Commands'''
::::::[[FACT show destinations|'''show destinations''']]
::::::[[FACT show egress ports|'''show egress ports''']]
::::::[[FACT show multicast routes|'''show multicast routes''']]
::::::[[FACT show multicast egress ports|'''show multicast egress ports''']]
::::::[[FACT show routes|'''show routes''']]

FACT show egress ports

2008-06-12T18:18:20Z

Lorlando:

To show the egress ports that forward unicast traffic to each specified destination port, use the '''show egress ports''' command.

::::::'''show egress ports''' [chassis | chip] [{to [''hosts'' | ''switches'' | ''ports'']} [guids]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Shows only switch chassis egress ports.
|-
|chip
|(Optional) Shows the egress port of each InfiniBand switch chip.
|-
|to
|(Optional) Identifies the destination set.
|-
|''hosts''
|(Optional) Shows only the egress ports to the specified hosts.
|-
|''switches''
|(Optional) Shows only the egress ports to the specified switches.
|-
|''ports''
|(Optional) Shows only the egress ports to the specified ports.
|-
|guids
|(Optional) Shows port GUIDs.
|-
|}

'''Command Default'''
::::::The default view is the chassis view.

'''Examples'''
::::::The following is sample output from the '''show egress ports''' command, and it shows all the unicast egress ports that route to host01:
fact> '''show egress ports to host01'''

Destination port host01/1/1, lid 792:
egress-port
--------------------------------
switchA/1/3
switchB/1/7

'''Related Commands'''
::::::[[FACT show destinations|'''show destinations''']]
::::::[[FACT show multicast routes|'''show multicast routes''']]
::::::[[FACT show multicast destinations|'''show multicast destinations''']]
::::::[[FACT show multicast egress ports|'''show multicast egress ports''']]
::::::[[FACT show routes|'''show routes''']]

FACT show destinations

2008-06-12T18:18:06Z

Lorlando:

To show the unicast destinations that are forwarded through each specified egress port, use the '''show destinations''' command.

::::::'''show destinations''' [''switches'' | ''ports''] [guids]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|''switches''
|(Optional) Shows destinations from the specified switch ports.
|-
|''ports''
|(Optional) Shows destinations from the specified ports.
|-
|guids
|(Optional) Shows GUIDs for each destination.
|}

'''Command Default'''
::::::If no port is specifed, then the default is to show all ports.

'''Examples'''
::::::The following is sample output from the '''show destinations''' command, and it shows all unicast destinations that egress chip switchA/1/3 through port 1:
fact> '''show destinations switchA/1:3/1'''

Egress port switchA/1:3/1:
destination lid
-------------------------------- -----
switchA/1:2/0 16
host01/1/1 792

'''Related Commands'''
::::::[[FACT show egress ports|'''show egress ports''']]
::::::[[FACT show multicast destinations|'''show multicast destinations''']]
::::::[[FACT show multicast egress ports|'''show multicast egress ports''']]
::::::[[FACT show multicast routes|'''show multicast routes''']]
::::::[[FACT show routes|'''show routes''']]

FACT show counters threshold

2008-06-12T18:17:52Z

Lorlando:

To display the monitored port counters, use the '''show counters threshold''' command.

::::::'''show counters threshold''' [chassis | chips | ports] [error]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Displays only the counters for the ports in the specified chassis.
|-
|chips
|(Optional) Displays only the counters for the ports in the specified chips.
|-
|ports
|(Optional) Displays only the counters for the specified ports.
|-
|error
|(Optional) Displays only those counters that are both error counters and non-zero counters. Some counters, such as xmit-pkts, count non-error events. These counters are not shown.
|}

'''Command Default'''
::::::No default behavior or values.

'''Usage Guidelines'''
::::::If the current scan does not include threshold port counters, then this command fails.

'''Examples'''
::::::The following is sample output from the '''show counters threshold''' command, and it shows all counters in the subnet that have exceeded their error thresholds:
fact> '''show counters threshold'''

port counter value
------------------------------ ----------------------------- ------------
port: switchB/1/3 symbol_errors 65535
ngbr: switchA/1/3
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
port: switchB/1/6 symbol_errors 65535
ngbr:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

'''Related Commands'''
::::::[[FACT reset port-counters|'''reset port-counters''']]
::::::[[FACT scan fabric|'''scan fabric''']]
::::::[[FACT scan fabric all|'''scan fabric all''']]
::::::[[FACT show counters monitored|'''show counters monitored''']]
::::::[[FACT show counters raw|'''show counters raw''']]

FACT show counters raw

2008-06-12T18:17:33Z

Lorlando:

To display the raw port counters, use the '''show counters raw''' command.

::::::'''show counters raw''' [chassis | chips | ports] [error]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Displays only the counters for the ports in the specified chassis.
|-
|chips
|(Optional) Displays only the counters for the ports in the specified chips.
|-
|ports
|(Optional) Displays only the counters for the specified ports.
|-
|error
|(Optional) Displays only those counters that are both error counters and non-zero counters. Some counters, such as xmit-pkts, count non-error events. These counters are not shown.
|}

'''Command Default'''
::::::No default behavior or values.

'''Usage Guidelines'''
::::::If the current scan does not include raw port counters, then this command fails.
::::::FACT does not display information for ports that have zero error counters only.

'''Examples'''
::::::The following is sample output from the '''show counters raw''' command, and it shows all the non-zero raw counters in the subnet. Errors have occurred on host01/1/1, switchB/1/3, switchB/1/6, and switchB/1/7. Three of the four ports have neighbors (ngbr), and switch switchB/1/6 does not have a neighbor. The example also lists the names and values of the non-zero counters.
fact> '''show counters raw error'''

port counter value
------------------------------ ----------------------------- ------------
port: host01/1/1 xmit_discards 3
ngbr: switchB/1/7 vl15_droppeds 7
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
port: switchB/1/3 symbol_errors 65535
ngbr: switchA/1/3 link_downs 3
xmit_discards 13
xmit_constraint_errors 13
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
port: switchB/1/6 symbol_errors 65535
ngbr: link_downs 1
xmit_discards 50
xmit_constraint_errors 50
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
port: switchB/1/7 rcv_switch_relay_errors 3
ngbr: host01/1/1
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

'''Related Commands'''
::::::[[FACT scan fabric|'''scan fabric''']]
::::::[[FACT scan fabric all|'''scan fabric all''']]
::::::[[FACT show counters monitored|'''show counters monitored''']]
::::::[[FACT show counters threshold|'''show counters threshold''']]
::::::[[FACT reset port-counters|'''reset port-counters''']]

FACT show counters monitored

2008-06-12T18:17:15Z

Lorlando:

To display the monitored port counters, use the '''show counters monitored''' command.

::::::'''show counters monitored''' [chassis | chips | ports] [error]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|chassis
|(Optional) Displays only the counters for the ports in the specified chassis.
|-
|chips
|(Optional) Displays only the counters for the ports in the specified chips.
|-
|ports
|(Optional) Displays only the counters for the specified ports.
|-
|error
|(Optional) Displays only those counters that are both error counters and non-zero counters. Some counters, such as xmit-pkts, count non-error events. These counters are not shown.
|}

'''Command Default'''
::::::No default behavior or values.

'''Usage Guidelines'''
::::::If the current scan does not include monitored port counters, then this command fails.
::::::FACT does not display information for ports that have zero error counters only.

'''Examples'''
::::::The following is sample output from the '''show counters monitored''' command, and it shows the monitored counters that have a non-zero error count:
fact> '''show counters monitored error'''

port counter value
------------------------------ ----------------------------- ------------
port: switchB/1/3 symbol_errors 65535
ngbr: switchA/1/3
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
port: switchB/1/6 symbol_errors 65535
ngbr:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

'''Related Commands'''
::::::[[FACT scan fabric|'''scan fabric''']]
::::::[[FACT scan fabric all|'''scan fabric all''']]
::::::[[FACT show counters raw|'''show counters raw''']]
::::::[[FACT show counters threshold|'''show counters threshold''']]
::::::[[FACT reset port-counters|'''reset port-counters''']]

FACT show changes

2008-06-12T18:16:50Z

Lorlando:

To compare the current scan with any specified scan in the repository, use the '''show changes''' command.

::::::'''show changes scan''' ''scan'' [''chassis'' | ''chips'' | ''ports'' | subnet-managers | sm]

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|''scan''
|Specifies the number of a particular scan to compare with the current scan.
|-
|''chassis''
|(Optional) Shows changes for only the specified chassis.
|-
|''chips''
|(Optional) Shows changes for only the specified chips.
|-
|''ports''
|(Optional) Shows changes for only the specified ports.
|-
|subnet-managers / sm
|(Optional) Reports changes to the subnet managers only.
|}

'''Command Default'''
::::::No default behavior or values.

'''Examples'''
::::::The following is sample output from the '''show changes''' command, and it shows the changes between scan 31 and the current scan:
fact> '''show changes scan 31'''
Old scan: 2007-10-23 05:46:14 PDT
New scan: 2007-11-01 12:02:21 PDT

Chassis:
No changes.

Chips:
Removed switch04/4:1
Removed switch04/4:2
Removed switch04/4:3
Added switch06/3:1
Added switch06/3:2
Added switch06/3:3

Neighbors:
Removed switch02/1/1 neighbor switch04/4/1
Added switch02/1/1 neighbor switch06/3/1

Subnet Managers:
Removed master host08/1/1
Removed standby host03/1/2
Added master host03/1/2
Added standby host12/1/1

'''Related Commands'''
::::::[[FACT show chassis|'''show chassis''']]
::::::[[FACT show chips|'''show chips''']]
::::::[[FACT show history|'''show history''']]
::::::[[FACT show ports|'''show ports''']]
::::::[[FACT show subnet-managers|'''show subnet-managers''']]

FACT scan fabric

2008-06-12T18:16:12Z

Lorlando:

To scan the static connectivity of the subnet and collect information from and about the Subnet Managers, use the '''scan fabric''' command.

::::::'''scan fabric''' [routes] [raw-counters] [monitored-counters] [threshold-counters] [subnet-manager | sm ''managed-node'']

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|routes
|(Optional) Collects routing information from the master Subnet Manager.
|-
|raw-counters
|(Optional) Collects raw port counters from the master Subnet Manager.
|-
|monitored-counters
|(Optional) Collects monitored port counters from the master Subnet Manager.
|-
|threshold-counters
|(Optional) Collects threshold-exceeded port counters.
|-
|subnet-manager
|(Optional) Overrides the discovered master Subnet Manager.
|-
|sm
|(Optional) Overrides the discovered master Subnet Manager.
|-
|''managed-node''
|(Optional) Scans the configured managed-nodes.
|}

'''Command Default'''
::::::No default behavior or values.

'''Usage Guidelines'''
::::::The scan will fail if the specified managed-node is not a master Subnet Manager.

'''Examples'''
::::::The following example shows scanning the fabric and also collecting route information and raw port counter information:
fact> '''scan fabric routes raw-counters'''
Scanning host01
Scanning switchA
Scanning switchB
Scanning Master Subnet Manager at host01

'''Related Commands'''
::::::[[FACT scan fabric all|'''scan fabric all''']]
::::::[[FACT scan tech-support|'''scan tech-support''']]
::::::[[FACT select| '''select''']]

FACT annotate

2008-06-12T18:14:42Z

Lorlando:

To annotate one or more syslog files and print them to the screen with annotations attached, use the '''annotate''' command.

::::::'''annotate''' [pass-through | filtered] [follow] [''files'']

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|pass-through
|(Optional) Indicates that all messages are printed to standard output.
|-
|filtered
|(Optional) Indicates that only those messages that are deemed important by FACT are printed.
|-
|follow
|(Optional) Specifies that FACT continuously watches for more records to be appended to the files and analyzes those records as they arrive.
|-
|''files''
|(Optional) Specifies the files to annotate (one file or multiple files).
|}

'''Command Default'''
::::::The default is '''pass-through''' ('''filtered''' for Alpha II release).

'''Usage Guidelines'''
::::::This command uses the current scan to perform annotations. If you specify no files, FACT looks in the FACT main configuration file and annotates only the files that are in the log-file parameters.

'''Examples'''
::::::The following example shows how FACT annotates a short log file:

fact> '''annotate mylogfile'''
Mar 21 20:14:28 herosm1 ib_sm[30456]: %IB-6-INFO: Generate SM IN_SERVICE trap for GID=fe:80:00:00:00:00:00:00:00:18:8b:90:97:fe:13:3a (hero0404/1/1, hero0404/1:1/1) (hero0404/1/1, hero0404/1:1/1, neighbor = 00:1b:0d:0b:00:00:8e:63 (leaf04b)/1/4)

'''Related Commands'''
::::::[[FACT ports speed|'''ports speed''']]

Fabric Analysis and Correlation Toolkit User Guide

2008-06-12T14:16:22Z

Lorlando:

This document provides an introduction to the Cisco Fabric Analysis and Correlation Toolkit (FACT). The information in this document supports Cisco FACT software Release 1.0, and it contains the following topics:

* [[FACT Overview|Overview]]
* [[How FACT Works]]
* [[FACT Quick Start Guide|Quick Start Guide]]
* [[Obtaining and Installing FACT]]
* [[FACT Configuration|Configuring FACT]]
* [[FACT Scanning|Using FACT]]
* [[FACT Command Reference|Command Reference]]
* [[FACT Support|Support]]
* [[FACT What's Coming?|What's Coming?]]

[[Category:Fabric Analysis and Correlation Toolkit]]
[[Category:Network Management]]

FACT export scan

2008-06-06T22:12:25Z

Lorlando:

To export the current scan to a file, use the '''export scan''' command.

::::::'''export scan''' to {''file''}

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|to
|Identifies the destination set.
|-
|''file''
|Exports the current scan to the specified file.
|}

'''Command Default'''
::::::No default behavior or values.

'''Examples'''
::::::The following example shows exporting the current scan to a file named "myscan":
fact> '''export scan to myscan'''

'''Related Commands'''
::::::[[FACT import scan|'''import scan''']]
::::::[[FACT export repository|'''export repository''']]
::::::[[FACT import repository|'''import repository''']]

FACT export scan

2008-06-06T22:12:13Z

Lorlando:

FACT export repository

2008-06-06T22:03:04Z

Lorlando:

To make a copy of the specified repository and save a copy of the FACT repository in a file, use the '''export repository''' command.

::::::'''export repository''' to {''file''}

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|to
|Identifies the destination set.
|-
|''file''
|Exports the current repository into the specified file.
|}

'''Command Default'''
::::::No default behavior or values

'''Examples'''
::::::The following example shows exporting the repository to a file named "myrepo":
fact> '''export repository to myrepo'''

'''Related Commands'''
::::::[[FACT export scan|'''export scan''']]
::::::[[FACT import repository|'''import repository''']]
::::::[[FACT import scan|'''import scan''']]

Using the CLI

2008-05-27T18:29:18Z

Lorlando: /* Command-line Options */

==Using FACT Command Arguments==

An argument is a text expression that denotes one or more objects in the fabric. Arguments are used as srguments to the FACT commands.

===Using Singular Arguments===

This section describes the syntax for each type of argument. [[Using the CLI#Using Singular Arguments|Table 1]] lists the argument syntax and the corresponding descriptions.

'''Table 1: Argument Syntax'''
{| border="1" cellpadding="10" cellspacing="0"
!Syntax
!Argument Description
|-
|''scan''
|Scans are numbered chronologically starting from 1. (1 is the oldest; N is the latest.) The latest scan can be specified as “latest.” The [[FACT show history|'''show history''']] command shows the number of each scan.
|-
|''file''
|A file or pathname is used by the FACT host platform.
|-
|''switch''
|A switch can be specified in one of the following ways:

*hostname or IP address of its management port, as specified in the managed-node definition. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
*chassis GUID, using the notation 00:11:22:33:44:55:66:77.
*given name of its chassis GUID (from guid name definition).
*description of one of its chips, prepended by “chassis,” as shown in the following example:

:chassis:00:11:22:33:44:55:66:77 (a node GUID)
|-
|''host''
|A host can be specified in one of the following ways:
*hostname or IP address, as specified in the managed-node definition.
*given name of its HCA node GUID (from guid name definitions).
*node GUID of its HCA, prepended by “chassis.”
|-
|''chassis''
|A chassis is either a host or a switch. Any of the previously listed notations for host or switch may be used.
|-
|''managed-node''
|A managed node is either a host or a switch. It must be specified exactly as it appears in the managed-node part of the configuration. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|''chip''
|A chip is an InfiniBand switch chip or InfiniBand channel adapter chip. It may be specified in the following ways:
*node GUID.
*given name from the GUID name definitions.
*the notation ''switch/slot:index'', where switch is a switch name, as described above, slot is a slot number (decimal integer) in a switch, and ''index'' is a decimal number. FACT orders chips in a slot by the node GUID. FACT numbers chips from 1 to n, ordered by their node GUIDs, going in ascending order from lowest to highest.
|-
|''port''
|A port may be specified as a port GUID, relative to a chassis or relative to a chip. As a port GUID, it is specified in eight hexadecimal octets separated by colons, as shown in the following example:
:00:02:c9:02:00:22:2a:c8

'''Note''': Most switch chips do not have port GUIDs.

Chassis-relative form has the '''syntax switch/slot/ext-number'', where ''ext-number'' is the external port number. ''Switch'' has any of the previously listed forms, as shown in the following example:
:switch01/2/3
:(port 3 on slot 2 of chassis switch01)

'''Note''': Internal chips can be specified in chip-relative syntax only.

Chip-relative form has the syntax ''chip/internal-number'', where chip is an InfiniBand chip as previously listed, and ''internal number'' is the port number on the chip, as shown in the following examples:
:switch01/2:3/4
:(chip port 4 on chip 3 of the card in slot 2 of chassis switch01)
:00:02:c9:02:00:22:2a:c4/4
:(chip port 4 on the chip with the given GUID)
|-
|''LID''
|A LID is a decimal integer.
|-
|''MLID''
|A multicast LID is a decimal integer.
|}

===Using Plural Arguments===

Many of the commands in FACT can accept plural arguments. The plurals can be built in several ways. Several alternatives can be separated by commas, with no spaces, as shown in the following example:
:switch01,switch02
Each alternative may contain one or more ranges. A range is surrounded by square brackets and contains one or more comma-separated alternatives. Each alternative may be a single value or a hyphen-separated range of values, as shown in the following example:
:rack[A-C,E]-host[01-10]
:(rackA-host01 through rackA-host10, and similarly for racks B, C, and E, skipping rackD)
Scans, LIDs, and slot, chip, and port numbers are always numeric, so ranges may be specified without the square brackets, as shown in the following example:
:switch03/1/1-4
:(ports 1 through 4 on slot 1 of chassis switch03)

A plural scan always describes a single object in a simple form (by not using any alternatives or images), as shown in the following example:
:switch03

FACT uses the following plural arguments:
*''LIDs''
*''chassis''
*''chips''
*''hosts''
*''managed-nodes''
*''multicast-groups''
*''ports''
*''scans''
*''switches''

'''Note''': Because all keywords can be abbreviated to a unique prefix, plural keywords such as chips and ports can be abbreviated to chip and port for the most common case of referring to a single unit. They keyword chassis can be either singular or plural.

==Using Command Modes==
FACT has two modes of operation:
*Interactive command-line processor mode
*Single-use command mode that performs a single function

===Using Interactive Mode===
As a command-line program, FACT reads commands from its input, parses them, and writes their output to its output. The following sample output shows FACT interactive mode:

$ fact
Cisco FACT 1.0
Copyright 2008, Cisco Systems, Inc.
fact> '''scan fabric'''
fact> '''show versions'''
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
fact> exit
$

===Using Single-Command Mode===
In single-command mode, a single command is passed to FACT as the program command arguments. FACT then runs the command, prints the results, and exits.

The following sample output shows the FACT single-command mode:

$ fact scan fabric
$ fact show versions
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
$

As a variant of single-command mode, the first word of the command, usually the verb, can be joined to the FACT name with a hyphen. The following sample output shows the FACT single-command mode:

$ '''fact-scan fabric'''
$ '''fact-show versions'''

To use shell completion to see available commands, join the FACT name with a hyphen, and enter the tab key:

$ '''fact'''-<TAB>

==Command-line Interface==

FACT looks for several environmental variables and accepts several command-line options.
This section describes the FACT command-line interface and shows how to use it.

===Command-line Options===

[[Using the CLI#Command-line Options|Table 2]] lists and describes the command-line options.

'''Table 2: Command-line Options'''

{| border="1" cellpadding="10" cellspacing="0"
!Option
!Description
|-
|'''-c''' ''file''
'''--config-file'''=''file''
|Reads primary configuration from the specified file.
|-
|'''--color'''='''always'''
|If tracing, specifies that the transcript is colorized, showing FACT requests in one color and the switch responses in another.
|-
|'''--color'''='''auto'''
|If tracing, specifies that the transcript is colorized only if the FACT standard output is a terminal. This behavior is the default.
|-
|'''--color'''='''never'''
|If tracing, specifies that the transcript is not colorized.
|-
|'''--config-option'''=
''option''
|Adds or overrides a configuration option.
|-
|'''--credentials-from'''=''file''
|Adds credential information from the file.
See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|'''--guid-name'''=''guid''=''name''
|Adds a GUID name definition.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]] section.
|-
|'''--guid-names-
from'''=''file''
|Adds GUID name definitions from the specified file.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|'''-h'''
'''--help'''
|Prints a message describing messages.
|-
|'''--help-commands'''
|Lists FACT commands.
|-
|'''--managed-nodes-'''=''type: pattern''
|Adds a set of managed-nodes to those about which FACT is aware.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].

|-
|'''--managed-nodes-from'''=''file''
|Adds managed-nodes from the file.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|'''-s'''
'''--sequential'''
|Initiates sequential scan sessions to one managed node at a time. This option is helpful with the '''--trace''' command because output displays slower and more predictably. By default, FACT connects up to 50 managed nodes at a time during scans and installations. If sequential is specified, then FACT connects to one managed node at a time.
|-
|'''--subnet-manager'''=''domain name'' or ''IP address''
|Specifies the InfiniBand Subnet Manager host that FACT should use.
|-
|'''--trace''' and '''--sequential'''
|Runs sequential sessions to managed nodes and prints the session transcript.
|-
|'''-t'''
'''--trace'''
|By default, if '''--trace''' is not specified, then FACT will print the transcript of each session when that session is closed. If '''--trace''' is specified, FACT will print the transcript of each session as it occurs.
|-
|'''-v'''
'''--version'''
|Prints FACT version information and exits.
|}

===Environment Variables===
FACT uses environment variables to control the FACT configuration. [[Using the CLI#Environment Variables|Table 3]] lists and describes the FACT environment variables.

'''Table 3: Environment Variables'''

{| border="1" cellpadding="10" cellspacing="0"
!Variable
!Description
|-
|FACT_CONF
|Name of master configturation file.
See [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].
|-
|FACT_CREDENTIAL_FILES
|List of files that contain credentials, separated by colons, as shown in the following example:

:FACT_CREDENTIAL_FILES=/etc/fact/cred1:/etc/fact/cred2
:states that the files /etc/fact/cred1 and /etc/fact/cred2 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|FACT_GUID_NAMES
|List of GUID name definitions, separated by semicolons. Each definition has the form “GUID=name,” as shown in the following example:
:FACT_GUID_NAMES="00:1b:0d:0b:00:00:ca:a6=switchA;00:1b:0d:0b:00:00:ca:aa=switchB"
:defines switchA as the name for 00:1b:0d:0b:00:00:ca:a6 and switchB as the name for 00:1b:0d:0b:00:00:ca:aa

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_GUID_NAME_FILES
|List of files containing GUID name definitions, separated by colons, as shown in the following example:
:FACT_GUID_NAME_FILES=/tmp/guidnames1:/tmp/guidnames2 states that the files /tmp/guidnames1 and /tmp/guidnames1 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_MANAGED_NODES
|In-line list of managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODES="host=ibmg-r1-evil:SFSOS switch=209.165.200.225
:defines a host named ibmg-r1-evil and an SFS OS switch named 209.165.200.225

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|FACT_MANAGED_NODE_FILES
|List of files containing managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODE_FILES=/tmp/nodefile1:/tmp/nodefile2
:states that the files /tmp/nodefile1 and /tmp/nodefile2 contain managed node definitions

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|}

===Correcting Commands===

'''Note''': This feature will be functional at FCS.

The system response to command line-errors is different when you use the question mark (?) to obtain help for a command. In this case, the system repeats your input following the subsequent prompt for ease of editing, as shown in the following example:

fact> show interfce ?
^
% Error: Unrecognized command
fact> show interfce

===Editing the CLI===

Command-line editing lets you modify a command line command that you have just entered or a command line that you entered previously in the CLI session. The CLI supports a variety of ways to move about and edit the currently displayed command line. [[Using the CLI#Editing the CLI|Table 4]] lists and describes these options.

'''Table 4: Key Stroke Shortcuts'''

{| border="1" cellpadding="10" cellspacing="0"
!Key Strokes
!Description
|-
|'''Ctrl'''-'''A'''
|Moves the cursor to the beginning of the line.
|-
|'''Ctrl'''-'''B'''
|Moves the cursor to the left (backward) one character.
|-
|'''Ctrl'''-'''D'''
|Deletes the current character. Exits FACT if the current input line is empty.
|-
|'''Ctrl'''-'''E'''
|Moves the cursor to the end of the line.
|-
|'''Ctrl'''-'''F'''
|Moves the cursor to the right (forward) one character.
|-
|'''Ctrl'''-'''G'''
|Erases the current input line.
|-
|'''Ctrl'''-'''H'''
|Deletes the character to the left of the cursor, analogous to the Backspace key.
|-
|'''Ctrl'''-'''I'''
|Completes the current word, analogous to the Tab key.
|-
|'''Ctrl'''-'''J'''
|Accepts the current line.
|-
|'''Ctrl'''-'''K'''
|Deletes text from the cursor to the end of the line.
|-
|'''Ctrl'''-'''L'''
|Refreshes the input line.
|-
|'''Ctrl'''-'''M'''
|Accepts the current line, analogous to the Return key.
|-
|'''Ctrl'''-'''N'''
|Proceeds to the next line in the command history.
|-
|'''Ctrl'''-'''P'''
|Moves to the previous line in the command history.
|-
|'''Ctrl'''-'''T'''
|Transposes the current and previous characters.
|-
|'''Ctrl'''-'''U'''
|Deletes all text to the left of the cursor, back to the beginning of the line.
|-
|'''Ctrl'''-'''W'''
|Deletes the word to the left of the cursor.
|-
|'''Ctrl'''-'''Z'''
|Suspends the FACT.
|-
|'''Ctrl'''-'''Del'''
|Deletes the chatacter to the left of the cursor, analogous to the Delete key.
|-
|'''?'''
|Completes the current word.
|-
|'''Esc'''-'''[A'''
|Moves to the previous line in the command history.
|-
|'''Esc'''-'''[B'''
|Proceeds to the next line in the command history.
|-
|'''Esc'''-'''[C'''
|Moves the cursor to the right (forward) one character.
|-
|'''Esc'''-'''[D'''
|Moves the cursor to the left (backward) on character.
|-
|'''Esc'''-'''B'''
|Moves the cursor to the left (backward) one word.
|-
|'''Esc'''-'''C'''
|Capitalizes the word to the right of the cursor (forward).
|-
|'''Esc'''-'''D'''
|Deletes characters from the cursor through the end of the word.
|-
|'''Esc'''-'''F'''
|Moves the cursor right (forward) one word.
|-
|'''Esc'''-'''L'''
|Converts characters, from the cursor to the end of the word, to lowercase.
|-
|'''Esc'''-'''U'''
|Converts characters, from the cursor to the end of the word, to uppercase.
|-
|'''Esc'''-'''Ctrl'''-'''H'''
|Deletes the word to the left of the cursor.
|-
|'''Esc'''-'''Delete'''
|Deletes the word to the left of the cursor.
|-
|'''Down Arrow'''
|Proceeds to the next line in the command history.
|-
|'''Up Arrow'''
|Moves to the previous line in the command history.
|-
|'''Left Arrow'''
|Moves the cursor to the left (backward) one character.
|-
|'''Right Arrow'''
|Moves the cursor to the right (forward) one character.
|}

[[Category:Command Line Interface]]

FACT Scanning

2008-05-27T17:15:50Z

Lorlando: /* Using Port Counters */

This section describes how to use FACT.

==Scanning==

Before FACT can perform other network tasks, you must first scan the network to determine which hosts and switches are in the network and to determine how they are connected. FACT scans an entire subnet at the same time, connecting to each managed Cisco switch and, optionally, to each port.

FACT has four scan types:

*'''Fabric scan'''--Finds the static configuration of the network. After collecting a fabric scan, FACT can display the network components and show how they are connected.

*'''Tech-support scan'''--Collects information that can be forwarded to a customer-support organization. A tech-support scan includes a fabric scan, which FACT can use, although FACT does not use the additional information. FACT saves that information for an expert to inspect.

*'''Port-counters scan'''--Collects port counters from the Performance Manager, in addition to the data collected in a fabric scan. See [[FACT Scanning#Using Port Counters|Using Port Counters]] for more information.

*'''Incomplete scan'''--A scan that has failed, either because of misconfiguration or because devices are not responding. The most common reason for an incomplete scan is either because the configuration does not include the device that is running the master Subnet Manager or because it includes two master Subnet Managers. In either case, change your configuration so that it includes exactly one master Subnet Manager. Alternately, you can force FACT to use the correct master Subnet Manager by setting ''subnet-manager:'' in the .fact.conf file or with the '''subnet-manager''' ''hostname'' command option.

'''Note''': If you are using the High-Performance Subnet Manager, then you must allow FACT to scan the hosts running HSM.

You can use the ''--trace'' command option to show FACT communication with each managed node as it scans.

Use the following commands to scan with FACT:
*[[FACT scan fabric|'''scan fabric''']]
*[[FACT scan tech-support|'''scan tech-support''']]

==Maintaining the Repository==

FACT maintains a repository that contains the results of past scans. FACT considers the last-performed scan in the repository as the current scan, which it uses for queries, annotations, port control, and firmware upgrades. Whenever you scan the network, the new scan becomes the current scan, although the repository has a history mechanism that allows the current scan to be rolled back to an earlier version.

By default, the repository is located at $HOME/.fact.

Use the [[FACT show history|'''show history''']] command to view all scans. Each scan has an index number that you use to select any particular scan. Use the [[FACT select|'''select''']] command to change the current scan.

The following example shows that the current scan is scan 6, as designated by the letter “Y”:

$ fact
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2007-12-27 19:37:25 PST ibmg-r1-120-1
2 fabric 2007-12-27 19:39:28 PST ibmg-r1-360-1
3 fabric 2008-01-03 17:09:51 PST kbob-s1
4 fabric 2008-01-03 20:14:50 PST 209.165.200.225
5 fabric 2008-01-08 15:30:29 PST kbob-s1
6 Y fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

From the current scan shown in the previous example, the following example shows selecting scan 4:
$ fact
fact> '''select 4'''
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2007-12-27 19:37:25 PST ibmg-r1-120-1
2 fabric 2007-12-27 19:39:28 PST ibmg-r1-360-1
3 fabric 2008-01-03 17:09:51 PST kbob-s1
4 Y fabric 2008-01-03 20:14:50 PST 209.165.200.225
5 fabric 2008-01-08 15:30:29 PST kbob-s1
6 fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

You can delete old scans by selecting the scan number from the index and using the [[FACT delete scans|'''delete scans''']] command.
The following example shows deleting the first three scans from the list in the previous example:
$ fact
fact> '''delete scans 1-3'''
Proceed with scan delete [Y/n]? '''y'''
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 Y fabric 2008-01-03 20:14:50 PST 209.165.200.225
2 fabric 2008-01-08 15:30:29 PST kbob-s1
3 fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

'''Note''': After you deleted scans 1 through 3, the scans that were previously listed as scans 4, 5, and 6 have remained, but they have now moved up in the index to become scans 1, 2, and 3.

You can export the current scan to a file with the [[FACT export scan|'''export scan''']] command, or you can export the entire repository with the [[FACT export repository|'''export repository''']] command. Similarly, you can import a scan with the [[FACT import scan|'''import scan''']] command or the import the entire repository with the [[FACT import repository|'''import repository''']] command.

If you need assistance in troubleshooting your network, you can use the [[FACT export repository|'''export repository''']] command. You can export the repository, save it to your specified location, and then make a copy to send to technical support.

You can clean out your repository with the [[FACT delete scans|'''delete scans''']] command.

'''Note''': Importing a repository deletes your existing repository and replaces it with the new repository that you import.

Use the following commands to maintain and manage your repository:
*[[FACT show history|'''show history''']]
*[[FACT select|'''select''']]
*[[FACT export scan|'''export scan''']]
*[[FACT export repository|'''export repository''']]
*[[FACT import repository|'''import repository''']]
*[[FACT import scan|'''import scan''']]
*[[FACT delete scans|'''delete scans''']]

==Showing Network Information==

Use the FACT [[FACT help|'''help''']] command to list all commands that are available. Generally, each query has several different output formats. The common formats are summary, guids, and detail.

The notation "someswitch/M/N" is called a chassis-view port name. The notation shows port N on slot M of chassis someswitch. The notation "someswitch/L:M/N" is a chip-view port name. The notation shows port N on chip M of slot L of chassis someswitch. Some switches require a mapping between external port numbers and chip-level port numbers. The chassis view uses external port numbers, and the chip view uses internal port numbers.

'''Note''': The colon character (":") appears only in the chip view, so its appearance in a string indicates that the string is in chip view notation.

The show ports command shows the ports and also the port neighbors of each port. If a port has no current neighbor, the last-known neighbor is shown. Last-known neighbors appear in square brackets ("[...]").

==Using Annotation==

When a file is annotated, FACT searches it for numeric constants and presents network components. It adds an annotation to each numeric constant, showing a human-readable name for that component.

FACT can annotate a log file or any file. When a file is annotated, FACT appends each GUID with a short explanation of what that GUID represents, as shown in the following example of an original log:

A port GUID is changed from this

:00:00:00:00:00:00:00:00

to this:

:00:00:00:00:00:00:00:00 (switch03/4/5, switch03/4:6/7, neighbor=switch12/2/3)

The preceding example shows the port chassis view and chip view, followed by the neighbor chassis view and chip view.

A node GUID is changed to this:

:00:00:00:00:00:00:00:00 (switch03/4:6)

A chassis GUID is changed to this:

:00:00:00:00:00:00:00:00 (switch03)

A LID is changed to this:

:23 (switch03/4/0, switch03/4:6/0, 00:00:00:00:00:00:00:00)

A port GID is changed to this:

:ff:12:60:1b:ff:ff:00:00:00:00:00:01:ff:33:2b:52 (switch03/4/0, switch03/4:6/0, neighbor=host14/1/1)

A Python source file, /usr/local/cisco/fact/annotation.py, contains sets of regular expression patterns for identifying interesting messages, for identifying messages containing node, chassis and port GUIDs and LIDs. Advanced users can edit that file to customize the syslog output.

[Add output here]

You can use the annotation as an element in a UNIX shell pipeline to annotate GUIDs in any command output, as shown in the following example:
:$ ibtstat | fact annotate /dev/stdin

You can pass an entire syslog through FACT annotation, as shown in the following example:
:$ fact annotate follow /var/logs/messages

If you do not provide a specific file with the annotate command, FACT looks for log-file parameters in the master configuration file.

'''Note''': Annotation always uses the current scan.

==Using Port Counters==

InfiniBand switch chips maintain a set of counters for each port. These counters count the occurrence of various types of errors. You can use FACT to collect and display port counters.

FACT can collect three types of port counter scans:

*'''Raw'''—The Subnet Manager does not need to be configured to collect raw port counters. FACT tells the Subnet Manager to enter every switch chip in the subnet to collect its port counters.
*'''Monitored'''—The Subnet Manager must be configured to collect monitored port counters. The Subnet Manager can be configured to monitor specified counters or all counters.
*'''Threshold'''—The Subnet Manager must be configured to collect threshold port counters. The threshold scan collects just those monitored port counters that have exceeded their error thresholds.

For information about configuring the Subnet Manager, see the ib pm command in the Cisco SFS Product Family Command Reference at this URL:
http://www.cisco.com/en/US/docs/server_nw_virtual/2.10.0_release/command/reference/cli210.html

For information about configuring the High-Performance Subnet Manager, see the '''config pm monitored state''' command and the '''config pm''' threshold command in the ''Cisco High-Performance Subnet Manager for InfiniBand Server Switches User Guide'' at this URL:
http://www.cisco.com/en/US/products/ps6985/products_installation_and_configuration_guides_list.html

FACT can scan the port counters in a network. Viewing the port counters is a three-stage process:
#Reset counters with the reset port-counters command. FACT records the reset in the scan history, which you can view later with the show history command.
#Scan the counters (wait a minimum of 60 seconds or longer for errors to occur). For more information about the port-counters scan, see the “Scanning” section.
#Show the port counters. To show the port counters or to restrict the output to those counters that are non-zero, use the '''show counters''' commands.

Consult the ''Cisco High Performance Subnet Manager for InfiniBand Server Switches User Guide'' or the ''Cisco SFS Product Family Command Reference'' for information about configuring port counter monitoring with the Cisco InfiniBand Subnet Manager.

Use the following commands to use port counters:
*[[FACT reset port-counters|'''reset port-counters''']]
*[[FACT show counters monitored|'''show counters monitored''']]
*[[FACT show counters raw|'''show counters raw''']]
*[[FACT show counters threshold|'''show counters threshold''']]

==Installing Firmware with FACT==

You can use FACT to install firmware on Cisco Server Fabric Switches running SFS OS, both on managed and unmanaged switches. Likewise, you can install firmware either on a single switch or on multiple switches simultaneously. (This firmware upgrade feature is not available for the OEM switches: Cisco SFS 7012 or Cisco SFS 7024.)

'''Note''': Because each firmware image is for a specific switch model, if you upgrade firmware on multiple switches simultaneously, all switches must be of the same model for which the firmware file is intended. FACT returns an error message if the firmware image does not match the switch model.

===Installing Firmware in Managed Switches===

To install firmware on a managed Cisco Server Fabric Switch, perform the following steps:

'''Step 1''' Log in to the host as a superuser.

'''Step 2''' Enter the [[FACT install|'''install''']] command to obtain and install the new firmware image. For an SFS OS switch, FACT instructs the switch to download the firmware from an FTP server, which you must set up in advance. The path argument must be an FTP URL with the following syntax:

:ftp://user:password@host/path/file

'''Step 3''' FACT checks the firmware on each switch that you want to upgrade and prints version numbers to the screen, grouped by version number. FACT then asks for confirmation. Confirm the version by typing '''y'''. FACT installs the new firmware on all specified switches.

'''Note''': When you install firmware on an SFS OS switch that is configured to be the master Subnet Manager, wait for at least one minute after the installation for the Subnet Manager to take control of the subnet before rescanning the fabric, or the scan fails and no master Subnet Manager is found.

The following example shows an SFS OS firmware upgrade from build 137 to build 154 on switches 1 through 2. The example shows that while the user attempted to upgrade switch 3, FACT determined that switch 3 was already running the updated build, and FACT disregarded the installation:

$ fact
fact> '''install switch[1-3] from'''
'''ftp://user:passwd@host/path/Topspin90-TopspinOS-2.8.0-build154.img'''
Checking switch1
Checking switch2
Checking switch3
These switches are running TopspinOS 2.8.0 build 137:
switch1
switch2
These switches are running TopspinOS 2.8.0 build 154:
switch3
Install [Y/n]?y
Installing switch1
Installing switch2
Skipping switch3
Waiting for switch1
Waiting for switch2
Waiting for switch3
switch1 rebooted
switch2 rebooted
switch3 rebooted
Rescan fabric to update switch versions

'''Step 4''' Enter the [[FACT scan fabric|'''scan fabric''']] command so that FACT can learn the current version that the switches are running.

'''Step 5''' Enter the [[FACT show versions|'''show versions''']] command to ensure that the correct version appears in the output.

===Installing Firmware in Unmanaged Switches===

For unmanaged switches, FACT uses the ibspark tool to install firmware. The ibspark tool transmits the firmware through InfiniBand to the switch, so the tool must run on a host that is directly connected to the InfiniBand network. However, ibspark is not required to reside on the same host as FACT. FACT can use SSH to reach the host with ibspark. (For information about obtaining the ibspark tool, see [[Obtaining and Installing FACT#Obtaining and Installing Optional Software Tools|Obtaining and Installing Optional Software Tools]] .) (For information about configuring FACT to use ibspark, see [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].)

To install firmware on an unmanaged Cisco Server Fabric Switch, perform the following steps:

'''Step 1''' Log in to the host as a superuser.

'''Step 2''' Enter the [[FACT install|'''install''']] command to obtain and install the new firmware image. For an unmanaged switch, the file parameter is a regular firmware image file. A firmware image file ends in .img.

'''Step 3''' FACT checks the firmware version on each switch that you want to upgrade and prints the version numbers to the screen, grouped by version number. FACT then asks for confirmation.
: Confirm the version by typing '''Y'''. FACT installs the new firmware on all specified switches.

The following example shows a firmware upgrade on unmanaged switches 4 through 6:

$ fact
fact> '''install switch[4-6] from somefile.img'''
Checking switch4
Checking switch5
Checking switch6
These switches are running version 1.2.3:
switch4
switch5
Install [Y/n]?y
Installing switch4
Installing switch5
Skipping switch6
Switches are rebooting. Rescan fabric after network stabilizes.
fact>

'''Step 4''' Enter the [[FACT scan fabric|'''scan fabric command''']] so that FACT can learn the current version that the switches are running.

'''Step 5''' Enter the [[FACT show versions|'''show versions''']] command to ensure that the correct version appears in the output.

FACT Scanning

2008-05-27T17:14:49Z

Lorlando: /* Using Port Counters */

This section describes how to use FACT.

==Scanning==

Before FACT can perform other network tasks, you must first scan the network to determine which hosts and switches are in the network and to determine how they are connected. FACT scans an entire subnet at the same time, connecting to each managed Cisco switch and, optionally, to each port.

FACT has four scan types:

*'''Fabric scan'''--Finds the static configuration of the network. After collecting a fabric scan, FACT can display the network components and show how they are connected.

*'''Tech-support scan'''--Collects information that can be forwarded to a customer-support organization. A tech-support scan includes a fabric scan, which FACT can use, although FACT does not use the additional information. FACT saves that information for an expert to inspect.

*'''Port-counters scan'''--Collects port counters from the Performance Manager, in addition to the data collected in a fabric scan. See [[FACT Scanning#Using Port Counters|Using Port Counters]] for more information.

*'''Incomplete scan'''--A scan that has failed, either because of misconfiguration or because devices are not responding. The most common reason for an incomplete scan is either because the configuration does not include the device that is running the master Subnet Manager or because it includes two master Subnet Managers. In either case, change your configuration so that it includes exactly one master Subnet Manager. Alternately, you can force FACT to use the correct master Subnet Manager by setting ''subnet-manager:'' in the .fact.conf file or with the '''subnet-manager''' ''hostname'' command option.

'''Note''': If you are using the High-Performance Subnet Manager, then you must allow FACT to scan the hosts running HSM.

You can use the ''--trace'' command option to show FACT communication with each managed node as it scans.

Use the following commands to scan with FACT:
*[[FACT scan fabric|'''scan fabric''']]
*[[FACT scan tech-support|'''scan tech-support''']]

==Maintaining the Repository==

FACT maintains a repository that contains the results of past scans. FACT considers the last-performed scan in the repository as the current scan, which it uses for queries, annotations, port control, and firmware upgrades. Whenever you scan the network, the new scan becomes the current scan, although the repository has a history mechanism that allows the current scan to be rolled back to an earlier version.

By default, the repository is located at $HOME/.fact.

Use the [[FACT show history|'''show history''']] command to view all scans. Each scan has an index number that you use to select any particular scan. Use the [[FACT select|'''select''']] command to change the current scan.

The following example shows that the current scan is scan 6, as designated by the letter “Y”:

$ fact
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2007-12-27 19:37:25 PST ibmg-r1-120-1
2 fabric 2007-12-27 19:39:28 PST ibmg-r1-360-1
3 fabric 2008-01-03 17:09:51 PST kbob-s1
4 fabric 2008-01-03 20:14:50 PST 209.165.200.225
5 fabric 2008-01-08 15:30:29 PST kbob-s1
6 Y fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

From the current scan shown in the previous example, the following example shows selecting scan 4:
$ fact
fact> '''select 4'''
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2007-12-27 19:37:25 PST ibmg-r1-120-1
2 fabric 2007-12-27 19:39:28 PST ibmg-r1-360-1
3 fabric 2008-01-03 17:09:51 PST kbob-s1
4 Y fabric 2008-01-03 20:14:50 PST 209.165.200.225
5 fabric 2008-01-08 15:30:29 PST kbob-s1
6 fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

You can delete old scans by selecting the scan number from the index and using the [[FACT delete scans|'''delete scans''']] command.
The following example shows deleting the first three scans from the list in the previous example:
$ fact
fact> '''delete scans 1-3'''
Proceed with scan delete [Y/n]? '''y'''
fact> '''show history'''
index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 Y fabric 2008-01-03 20:14:50 PST 209.165.200.225
2 fabric 2008-01-08 15:30:29 PST kbob-s1
3 fabric 2008-01-08 15:33:52 PST kbob-s1
fact>

'''Note''': After you deleted scans 1 through 3, the scans that were previously listed as scans 4, 5, and 6 have remained, but they have now moved up in the index to become scans 1, 2, and 3.

You can export the current scan to a file with the [[FACT export scan|'''export scan''']] command, or you can export the entire repository with the [[FACT export repository|'''export repository''']] command. Similarly, you can import a scan with the [[FACT import scan|'''import scan''']] command or the import the entire repository with the [[FACT import repository|'''import repository''']] command.

If you need assistance in troubleshooting your network, you can use the [[FACT export repository|'''export repository''']] command. You can export the repository, save it to your specified location, and then make a copy to send to technical support.

You can clean out your repository with the [[FACT delete scans|'''delete scans''']] command.

'''Note''': Importing a repository deletes your existing repository and replaces it with the new repository that you import.

Use the following commands to maintain and manage your repository:
*[[FACT show history|'''show history''']]
*[[FACT select|'''select''']]
*[[FACT export scan|'''export scan''']]
*[[FACT export repository|'''export repository''']]
*[[FACT import repository|'''import repository''']]
*[[FACT import scan|'''import scan''']]
*[[FACT delete scans|'''delete scans''']]

==Showing Network Information==

Use the FACT [[FACT help|'''help''']] command to list all commands that are available. Generally, each query has several different output formats. The common formats are summary, guids, and detail.

The notation "someswitch/M/N" is called a chassis-view port name. The notation shows port N on slot M of chassis someswitch. The notation "someswitch/L:M/N" is a chip-view port name. The notation shows port N on chip M of slot L of chassis someswitch. Some switches require a mapping between external port numbers and chip-level port numbers. The chassis view uses external port numbers, and the chip view uses internal port numbers.

'''Note''': The colon character (":") appears only in the chip view, so its appearance in a string indicates that the string is in chip view notation.

The show ports command shows the ports and also the port neighbors of each port. If a port has no current neighbor, the last-known neighbor is shown. Last-known neighbors appear in square brackets ("[...]").

==Using Annotation==

When a file is annotated, FACT searches it for numeric constants and presents network components. It adds an annotation to each numeric constant, showing a human-readable name for that component.

FACT can annotate a log file or any file. When a file is annotated, FACT appends each GUID with a short explanation of what that GUID represents, as shown in the following example of an original log:

A port GUID is changed from this

:00:00:00:00:00:00:00:00

to this:

:00:00:00:00:00:00:00:00 (switch03/4/5, switch03/4:6/7, neighbor=switch12/2/3)

The preceding example shows the port chassis view and chip view, followed by the neighbor chassis view and chip view.

A node GUID is changed to this:

:00:00:00:00:00:00:00:00 (switch03/4:6)

A chassis GUID is changed to this:

:00:00:00:00:00:00:00:00 (switch03)

A LID is changed to this:

:23 (switch03/4/0, switch03/4:6/0, 00:00:00:00:00:00:00:00)

A port GID is changed to this:

:ff:12:60:1b:ff:ff:00:00:00:00:00:01:ff:33:2b:52 (switch03/4/0, switch03/4:6/0, neighbor=host14/1/1)

A Python source file, /usr/local/cisco/fact/annotation.py, contains sets of regular expression patterns for identifying interesting messages, for identifying messages containing node, chassis and port GUIDs and LIDs. Advanced users can edit that file to customize the syslog output.

[Add output here]

You can use the annotation as an element in a UNIX shell pipeline to annotate GUIDs in any command output, as shown in the following example:
:$ ibtstat | fact annotate /dev/stdin

You can pass an entire syslog through FACT annotation, as shown in the following example:
:$ fact annotate follow /var/logs/messages

If you do not provide a specific file with the annotate command, FACT looks for log-file parameters in the master configuration file.

'''Note''': Annotation always uses the current scan.

==Using Port Counters==

InfiniBand switch chips maintain a set of counters for each port. These counters count the occurrence of various types of errors. You can use FACT to collect and display port counters.

FACT can collect three types of port counter scans:

*'''Raw'''—The Subnet Manager does not need to be configured to collect raw port counters. FACT tells the Subnet Manager to enter every switch chip in the subnet to collect its port counters.
*'''Monitored'''—The Subnet Manager must be configured to collect monitored port counters. The Subnet Manager can be configured to monitor specified counters or all counters.
*'''Threshold'''—The Subnet Manager must be configured to collect threshold port counters. The threshold scan collects just those monitored port counters that have exceeded their error thresholds.

For information about configuring the Subnet Manager, see the ib pm command in the Cisco SFS Product Family Command Reference at this URL:
http://www.cisco.com/en/US/docs/server_nw_virtual/2.10.0_release/command/reference/cli210.html

For information about configuring the High-Performance Subnet Manager, see the '''config pm monitored state''' command and the '''config pm''' threshold command in the Cisco High-Performance Subnet Manager User Guide at this URL:
http://www.cisco.com/en/US/products/ps6985/products_installation_and_configuration_guides_list.html

FACT can scan the port counters in a network. Viewing the port counters is a three-stage process:
#Reset counters with the reset port-counters command. FACT records the reset in the scan history, which you can view later with the show history command.
#Scan the counters (wait a minimum of 60 seconds or longer for errors to occur). For more information about the port-counters scan, see the “Scanning” section.
#Show the port counters. To show the port counters or to restrict the output to those counters that are non-zero, use the '''show counters''' commands.

Consult the ''Cisco High Performance Subnet Manager for InfiniBand Server Switches User Guide'' or the ''Cisco SFS Product Family Command Reference'' for information about configuring port counter monitoring with the Cisco InfiniBand Subnet Manager.

Use the following commands to use port counters:
*[[FACT reset port-counters|'''reset port-counters''']]
*[[FACT show counters monitored|'''show counters monitored''']]
*[[FACT show counters raw|'''show counters raw''']]
*[[FACT show counters threshold|'''show counters threshold''']]

==Installing Firmware with FACT==

You can use FACT to install firmware on Cisco Server Fabric Switches running SFS OS, both on managed and unmanaged switches. Likewise, you can install firmware either on a single switch or on multiple switches simultaneously. (This firmware upgrade feature is not available for the OEM switches: Cisco SFS 7012 or Cisco SFS 7024.)

'''Note''': Because each firmware image is for a specific switch model, if you upgrade firmware on multiple switches simultaneously, all switches must be of the same model for which the firmware file is intended. FACT returns an error message if the firmware image does not match the switch model.

===Installing Firmware in Managed Switches===

To install firmware on a managed Cisco Server Fabric Switch, perform the following steps:

'''Step 1''' Log in to the host as a superuser.

'''Step 2''' Enter the [[FACT install|'''install''']] command to obtain and install the new firmware image. For an SFS OS switch, FACT instructs the switch to download the firmware from an FTP server, which you must set up in advance. The path argument must be an FTP URL with the following syntax:

:ftp://user:password@host/path/file

'''Step 3''' FACT checks the firmware on each switch that you want to upgrade and prints version numbers to the screen, grouped by version number. FACT then asks for confirmation. Confirm the version by typing '''y'''. FACT installs the new firmware on all specified switches.

'''Note''': When you install firmware on an SFS OS switch that is configured to be the master Subnet Manager, wait for at least one minute after the installation for the Subnet Manager to take control of the subnet before rescanning the fabric, or the scan fails and no master Subnet Manager is found.

The following example shows an SFS OS firmware upgrade from build 137 to build 154 on switches 1 through 2. The example shows that while the user attempted to upgrade switch 3, FACT determined that switch 3 was already running the updated build, and FACT disregarded the installation:

$ fact
fact> '''install switch[1-3] from'''
'''ftp://user:passwd@host/path/Topspin90-TopspinOS-2.8.0-build154.img'''
Checking switch1
Checking switch2
Checking switch3
These switches are running TopspinOS 2.8.0 build 137:
switch1
switch2
These switches are running TopspinOS 2.8.0 build 154:
switch3
Install [Y/n]?y
Installing switch1
Installing switch2
Skipping switch3
Waiting for switch1
Waiting for switch2
Waiting for switch3
switch1 rebooted
switch2 rebooted
switch3 rebooted
Rescan fabric to update switch versions

'''Step 4''' Enter the [[FACT scan fabric|'''scan fabric''']] command so that FACT can learn the current version that the switches are running.

'''Step 5''' Enter the [[FACT show versions|'''show versions''']] command to ensure that the correct version appears in the output.

===Installing Firmware in Unmanaged Switches===

For unmanaged switches, FACT uses the ibspark tool to install firmware. The ibspark tool transmits the firmware through InfiniBand to the switch, so the tool must run on a host that is directly connected to the InfiniBand network. However, ibspark is not required to reside on the same host as FACT. FACT can use SSH to reach the host with ibspark. (For information about obtaining the ibspark tool, see [[Obtaining and Installing FACT#Obtaining and Installing Optional Software Tools|Obtaining and Installing Optional Software Tools]] .) (For information about configuring FACT to use ibspark, see [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].)

To install firmware on an unmanaged Cisco Server Fabric Switch, perform the following steps:

'''Step 1''' Log in to the host as a superuser.

'''Step 2''' Enter the [[FACT install|'''install''']] command to obtain and install the new firmware image. For an unmanaged switch, the file parameter is a regular firmware image file. A firmware image file ends in .img.

'''Step 3''' FACT checks the firmware version on each switch that you want to upgrade and prints the version numbers to the screen, grouped by version number. FACT then asks for confirmation.
: Confirm the version by typing '''Y'''. FACT installs the new firmware on all specified switches.

The following example shows a firmware upgrade on unmanaged switches 4 through 6:

$ fact
fact> '''install switch[4-6] from somefile.img'''
Checking switch4
Checking switch5
Checking switch6
These switches are running version 1.2.3:
switch4
switch5
Install [Y/n]?y
Installing switch4
Installing switch5
Skipping switch6
Switches are rebooting. Rescan fabric after network stabilizes.
fact>

'''Step 4''' Enter the [[FACT scan fabric|'''scan fabric command''']] so that FACT can learn the current version that the switches are running.

'''Step 5''' Enter the [[FACT show versions|'''show versions''']] command to ensure that the correct version appears in the output.

Using the CLI

2008-05-27T17:10:22Z

Lorlando: /* Command-line Options */

==Using FACT Command Arguments==

An argument is a text expression that denotes one or more objects in the fabric. Arguments are used as srguments to the FACT commands.

===Using Singular Arguments===

This section describes the syntax for each type of argument. [[Using the CLI#Using Singular Arguments|Table 1]] lists the argument syntax and the corresponding descriptions.

'''Table 1: Argument Syntax'''
{| border="1" cellpadding="10" cellspacing="0"
!Syntax
!Argument Description
|-
|''scan''
|Scans are numbered chronologically starting from 1. (1 is the oldest; N is the latest.) The latest scan can be specified as “latest.” The [[FACT show history|'''show history''']] command shows the number of each scan.
|-
|''file''
|A file or pathname is used by the FACT host platform.
|-
|''switch''
|A switch can be specified in one of the following ways:

*hostname or IP address of its management port, as specified in the managed-node definition. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
*chassis GUID, using the notation 00:11:22:33:44:55:66:77.
*given name of its chassis GUID (from guid name definition).
*description of one of its chips, prepended by “chassis,” as shown in the following example:

:chassis:00:11:22:33:44:55:66:77 (a node GUID)
|-
|''host''
|A host can be specified in one of the following ways:
*hostname or IP address, as specified in the managed-node definition.
*given name of its HCA node GUID (from guid name definitions).
*node GUID of its HCA, prepended by “chassis.”
|-
|''chassis''
|A chassis is either a host or a switch. Any of the previously listed notations for host or switch may be used.
|-
|''managed-node''
|A managed node is either a host or a switch. It must be specified exactly as it appears in the managed-node part of the configuration. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|''chip''
|A chip is an InfiniBand switch chip or InfiniBand channel adapter chip. It may be specified in the following ways:
*node GUID.
*given name from the GUID name definitions.
*the notation ''switch/slot:index'', where switch is a switch name, as described above, slot is a slot number (decimal integer) in a switch, and ''index'' is a decimal number. FACT orders chips in a slot by the node GUID. FACT numbers chips from 1 to n, ordered by their node GUIDs, going in ascending order from lowest to highest.
|-
|''port''
|A port may be specified as a port GUID, relative to a chassis or relative to a chip. As a port GUID, it is specified in eight hexadecimal octets separated by colons, as shown in the following example:
:00:02:c9:02:00:22:2a:c8

'''Note''': Most switch chips do not have port GUIDs.

Chassis-relative form has the '''syntax switch/slot/ext-number'', where ''ext-number'' is the external port number. ''Switch'' has any of the previously listed forms, as shown in the following example:
:switch01/2/3
:(port 3 on slot 2 of chassis switch01)

'''Note''': Internal chips can be specified in chip-relative syntax only.

Chip-relative form has the syntax ''chip/internal-number'', where chip is an InfiniBand chip as previously listed, and ''internal number'' is the port number on the chip, as shown in the following examples:
:switch01/2:3/4
:(chip port 4 on chip 3 of the card in slot 2 of chassis switch01)
:00:02:c9:02:00:22:2a:c4/4
:(chip port 4 on the chip with the given GUID)
|-
|''LID''
|A LID is a decimal integer.
|-
|''MLID''
|A multicast LID is a decimal integer.
|}

===Using Plural Arguments===

Many of the commands in FACT can accept plural arguments. The plurals can be built in several ways. Several alternatives can be separated by commas, with no spaces, as shown in the following example:
:switch01,switch02
Each alternative may contain one or more ranges. A range is surrounded by square brackets and contains one or more comma-separated alternatives. Each alternative may be a single value or a hyphen-separated range of values, as shown in the following example:
:rack[A-C,E]-host[01-10]
:(rackA-host01 through rackA-host10, and similarly for racks B, C, and E, skipping rackD)
Scans, LIDs, and slot, chip, and port numbers are always numeric, so ranges may be specified without the square brackets, as shown in the following example:
:switch03/1/1-4
:(ports 1 through 4 on slot 1 of chassis switch03)

A plural scan always describes a single object in a simple form (by not using any alternatives or images), as shown in the following example:
:switch03

FACT uses the following plural arguments:
*''LIDs''
*''chassis''
*''chips''
*''hosts''
*''managed-nodes''
*''multicast-groups''
*''ports''
*''scans''
*''switches''

'''Note''': Because all keywords can be abbreviated to a unique prefix, plural keywords such as chips and ports can be abbreviated to chip and port for the most common case of referring to a single unit. They keyword chassis can be either singular or plural.

==Using Command Modes==
FACT has two modes of operation:
*Interactive command-line processor mode
*Single-use command mode that performs a single function

===Using Interactive Mode===
As a command-line program, FACT reads commands from its input, parses them, and writes their output to its output. The following sample output shows FACT interactive mode:

$ fact
Cisco FACT 1.0
Copyright 2008, Cisco Systems, Inc.
fact> '''scan fabric'''
fact> '''show versions'''
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
fact> exit
$

===Using Single-Command Mode===
In single-command mode, a single command is passed to FACT as the program command arguments. FACT then runs the command, prints the results, and exits.

The following sample output shows the FACT single-command mode:

$ fact scan fabric
$ fact show versions
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
$

As a variant of single-command mode, the first word of the command, usually the verb, can be joined to the FACT name with a hyphen. The following sample output shows the FACT single-command mode:

$ '''fact-scan fabric'''
$ '''fact-show versions'''

To use shell completion to see available commands, join the FACT name with a hyphen, and enter the tab key:

$ '''fact'''-<TAB>

==Command-line Interface==

FACT looks for several environmental variables and accepts several command-line options.
This section describes the FACT command-line interface and shows how to use it.

===Command-line Options===

[[Using the CLI#Command-line Options|Table 2]] lists and describes the command-line options.

'''Table 2: Command-line Options'''

{| border="1" cellpadding="10" cellspacing="0"
!Option
!Description
|-
|'''-c''' ''file''
'''--config-file'''=''file''
|Reads primary configuration from the specified file.
|-
|'''--color'''='''always'''
|If tracing, specifies that the transcript is colorized, showing FACT requests in one color and the switch responses in another.
|-
|'''--color'''='''auto'''
|If tracing, specifies that the transcript is colorized only if the FACT standard output is a terminal. This behavior is the default.
|-
|'''--config-option'''=
''option''
|Adds or overrides a configuration option.
|-
|'''--credentials-from'''=''file''
|Adds credential information from the file.
See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|'''--guid-name'''=''guid''=''name''
|Adds a GUID name definition.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]] section.
|-
|'''--guid-names-
from'''=''file''
|Adds GUID name definitions from the specified file.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|'''-h'''
'''--help'''
|Prints a message describing messages.
|-
|'''--help-commands'''
|Lists FACT commands.
|-
|'''--managed-nodes-'''=''type: pattern''
|Adds a set of managed-nodes to those about which FACT is aware.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].

|-
|'''--managed-nodes-from'''=''file''
|Adds managed-nodes from the file.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|'''-s'''
'''--sequential'''
|Initiates sequential scan sessions to one managed node at a time. This option is helpful with the '''--trace''' command because output displays slower and more predictably. By default, FACT connects up to 50 managed nodes at a time during scans and installations. If sequential is specified, then FACT connects to one managed node at a time.
|-
|'''--subnet-manager'''=''domain name'' or ''IP address''
|Specifies the InfiniBand Subnet Manager host that FACT should use.
|-
|'''--trace''' and '''--sequential'''
|Runs sequential sessions to managed nodes and prints the session transcript.
|-
|'''-t'''
'''--trace'''
|By default, if '''--trace''' is not specified, then FACT will print the transcript of each session when that session is closed. If '''--trace''' is specified, FACT will print the transcript of each session as it occurs.
|-
|'''-v'''
'''--version'''
|Prints FACT version information and exits.
|}

===Environment Variables===
FACT uses environment variables to control the FACT configuration. [[Using the CLI#Environment Variables|Table 3]] lists and describes the FACT environment variables.

'''Table 3: Environment Variables'''

{| border="1" cellpadding="10" cellspacing="0"
!Variable
!Description
|-
|FACT_CONF
|Name of master configturation file.
See [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].
|-
|FACT_CREDENTIAL_FILES
|List of files that contain credentials, separated by colons, as shown in the following example:

:FACT_CREDENTIAL_FILES=/etc/fact/cred1:/etc/fact/cred2
:states that the files /etc/fact/cred1 and /etc/fact/cred2 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|FACT_GUID_NAMES
|List of GUID name definitions, separated by semicolons. Each definition has the form “GUID=name,” as shown in the following example:
:FACT_GUID_NAMES="00:1b:0d:0b:00:00:ca:a6=switchA;00:1b:0d:0b:00:00:ca:aa=switchB"
:defines switchA as the name for 00:1b:0d:0b:00:00:ca:a6 and switchB as the name for 00:1b:0d:0b:00:00:ca:aa

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_GUID_NAME_FILES
|List of files containing GUID name definitions, separated by colons, as shown in the following example:
:FACT_GUID_NAME_FILES=/tmp/guidnames1:/tmp/guidnames2 states that the files /tmp/guidnames1 and /tmp/guidnames1 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_MANAGED_NODES
|In-line list of managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODES="host=ibmg-r1-evil:SFSOS switch=209.165.200.225
:defines a host named ibmg-r1-evil and an SFS OS switch named 209.165.200.225

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|FACT_MANAGED_NODE_FILES
|List of files containing managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODE_FILES=/tmp/nodefile1:/tmp/nodefile2
:states that the files /tmp/nodefile1 and /tmp/nodefile2 contain managed node definitions

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|}

===Correcting Commands===

'''Note''': This feature will be functional at FCS.

The system response to command line-errors is different when you use the question mark (?) to obtain help for a command. In this case, the system repeats your input following the subsequent prompt for ease of editing, as shown in the following example:

fact> show interfce ?
^
% Error: Unrecognized command
fact> show interfce

===Editing the CLI===

Command-line editing lets you modify a command line command that you have just entered or a command line that you entered previously in the CLI session. The CLI supports a variety of ways to move about and edit the currently displayed command line. [[Using the CLI#Editing the CLI|Table 4]] lists and describes these options.

'''Table 4: Key Stroke Shortcuts'''

{| border="1" cellpadding="10" cellspacing="0"
!Key Strokes
!Description
|-
|'''Ctrl'''-'''A'''
|Moves the cursor to the beginning of the line.
|-
|'''Ctrl'''-'''B'''
|Moves the cursor to the left (backward) one character.
|-
|'''Ctrl'''-'''D'''
|Deletes the current character. Exits FACT if the current input line is empty.
|-
|'''Ctrl'''-'''E'''
|Moves the cursor to the end of the line.
|-
|'''Ctrl'''-'''F'''
|Moves the cursor to the right (forward) one character.
|-
|'''Ctrl'''-'''G'''
|Erases the current input line.
|-
|'''Ctrl'''-'''H'''
|Deletes the character to the left of the cursor, analogous to the Backspace key.
|-
|'''Ctrl'''-'''I'''
|Completes the current word, analogous to the Tab key.
|-
|'''Ctrl'''-'''J'''
|Accepts the current line.
|-
|'''Ctrl'''-'''K'''
|Deletes text from the cursor to the end of the line.
|-
|'''Ctrl'''-'''L'''
|Refreshes the input line.
|-
|'''Ctrl'''-'''M'''
|Accepts the current line, analogous to the Return key.
|-
|'''Ctrl'''-'''N'''
|Proceeds to the next line in the command history.
|-
|'''Ctrl'''-'''P'''
|Moves to the previous line in the command history.
|-
|'''Ctrl'''-'''T'''
|Transposes the current and previous characters.
|-
|'''Ctrl'''-'''U'''
|Deletes all text to the left of the cursor, back to the beginning of the line.
|-
|'''Ctrl'''-'''W'''
|Deletes the word to the left of the cursor.
|-
|'''Ctrl'''-'''Z'''
|Suspends the FACT.
|-
|'''Ctrl'''-'''Del'''
|Deletes the chatacter to the left of the cursor, analogous to the Delete key.
|-
|'''?'''
|Completes the current word.
|-
|'''Esc'''-'''[A'''
|Moves to the previous line in the command history.
|-
|'''Esc'''-'''[B'''
|Proceeds to the next line in the command history.
|-
|'''Esc'''-'''[C'''
|Moves the cursor to the right (forward) one character.
|-
|'''Esc'''-'''[D'''
|Moves the cursor to the left (backward) on character.
|-
|'''Esc'''-'''B'''
|Moves the cursor to the left (backward) one word.
|-
|'''Esc'''-'''C'''
|Capitalizes the word to the right of the cursor (forward).
|-
|'''Esc'''-'''D'''
|Deletes characters from the cursor through the end of the word.
|-
|'''Esc'''-'''F'''
|Moves the cursor right (forward) one word.
|-
|'''Esc'''-'''L'''
|Converts characters, from the cursor to the end of the word, to lowercase.
|-
|'''Esc'''-'''U'''
|Converts characters, from the cursor to the end of the word, to uppercase.
|-
|'''Esc'''-'''Ctrl'''-'''H'''
|Deletes the word to the left of the cursor.
|-
|'''Esc'''-'''Delete'''
|Deletes the word to the left of the cursor.
|-
|'''Down Arrow'''
|Proceeds to the next line in the command history.
|-
|'''Up Arrow'''
|Moves to the previous line in the command history.
|-
|'''Left Arrow'''
|Moves the cursor to the left (backward) one character.
|-
|'''Right Arrow'''
|Moves the cursor to the right (forward) one character.
|}

[[Category:Command Line Interface]]

Using the CLI

2008-05-27T17:05:23Z

Lorlando: /* Command-line Interface */

==Using FACT Command Arguments==

An argument is a text expression that denotes one or more objects in the fabric. Arguments are used as srguments to the FACT commands.

===Using Singular Arguments===

This section describes the syntax for each type of argument. [[Using the CLI#Using Singular Arguments|Table 1]] lists the argument syntax and the corresponding descriptions.

'''Table 1: Argument Syntax'''
{| border="1" cellpadding="10" cellspacing="0"
!Syntax
!Argument Description
|-
|''scan''
|Scans are numbered chronologically starting from 1. (1 is the oldest; N is the latest.) The latest scan can be specified as “latest.” The [[FACT show history|'''show history''']] command shows the number of each scan.
|-
|''file''
|A file or pathname is used by the FACT host platform.
|-
|''switch''
|A switch can be specified in one of the following ways:

*hostname or IP address of its management port, as specified in the managed-node definition. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
*chassis GUID, using the notation 00:11:22:33:44:55:66:77.
*given name of its chassis GUID (from guid name definition).
*description of one of its chips, prepended by “chassis,” as shown in the following example:

:chassis:00:11:22:33:44:55:66:77 (a node GUID)
|-
|''host''
|A host can be specified in one of the following ways:
*hostname or IP address, as specified in the managed-node definition.
*given name of its HCA node GUID (from guid name definitions).
*node GUID of its HCA, prepended by “chassis.”
|-
|''chassis''
|A chassis is either a host or a switch. Any of the previously listed notations for host or switch may be used.
|-
|''managed-node''
|A managed node is either a host or a switch. It must be specified exactly as it appears in the managed-node part of the configuration. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|''chip''
|A chip is an InfiniBand switch chip or InfiniBand channel adapter chip. It may be specified in the following ways:
*node GUID.
*given name from the GUID name definitions.
*the notation ''switch/slot:index'', where switch is a switch name, as described above, slot is a slot number (decimal integer) in a switch, and ''index'' is a decimal number. FACT orders chips in a slot by the node GUID. FACT numbers chips from 1 to n, ordered by their node GUIDs, going in ascending order from lowest to highest.
|-
|''port''
|A port may be specified as a port GUID, relative to a chassis or relative to a chip. As a port GUID, it is specified in eight hexadecimal octets separated by colons, as shown in the following example:
:00:02:c9:02:00:22:2a:c8

'''Note''': Most switch chips do not have port GUIDs.

Chassis-relative form has the '''syntax switch/slot/ext-number'', where ''ext-number'' is the external port number. ''Switch'' has any of the previously listed forms, as shown in the following example:
:switch01/2/3
:(port 3 on slot 2 of chassis switch01)

'''Note''': Internal chips can be specified in chip-relative syntax only.

Chip-relative form has the syntax ''chip/internal-number'', where chip is an InfiniBand chip as previously listed, and ''internal number'' is the port number on the chip, as shown in the following examples:
:switch01/2:3/4
:(chip port 4 on chip 3 of the card in slot 2 of chassis switch01)
:00:02:c9:02:00:22:2a:c4/4
:(chip port 4 on the chip with the given GUID)
|-
|''LID''
|A LID is a decimal integer.
|-
|''MLID''
|A multicast LID is a decimal integer.
|}

===Using Plural Arguments===

Many of the commands in FACT can accept plural arguments. The plurals can be built in several ways. Several alternatives can be separated by commas, with no spaces, as shown in the following example:
:switch01,switch02
Each alternative may contain one or more ranges. A range is surrounded by square brackets and contains one or more comma-separated alternatives. Each alternative may be a single value or a hyphen-separated range of values, as shown in the following example:
:rack[A-C,E]-host[01-10]
:(rackA-host01 through rackA-host10, and similarly for racks B, C, and E, skipping rackD)
Scans, LIDs, and slot, chip, and port numbers are always numeric, so ranges may be specified without the square brackets, as shown in the following example:
:switch03/1/1-4
:(ports 1 through 4 on slot 1 of chassis switch03)

A plural scan always describes a single object in a simple form (by not using any alternatives or images), as shown in the following example:
:switch03

FACT uses the following plural arguments:
*''LIDs''
*''chassis''
*''chips''
*''hosts''
*''managed-nodes''
*''multicast-groups''
*''ports''
*''scans''
*''switches''

'''Note''': Because all keywords can be abbreviated to a unique prefix, plural keywords such as chips and ports can be abbreviated to chip and port for the most common case of referring to a single unit. They keyword chassis can be either singular or plural.

==Using Command Modes==
FACT has two modes of operation:
*Interactive command-line processor mode
*Single-use command mode that performs a single function

===Using Interactive Mode===
As a command-line program, FACT reads commands from its input, parses them, and writes their output to its output. The following sample output shows FACT interactive mode:

$ fact
Cisco FACT 1.0
Copyright 2008, Cisco Systems, Inc.
fact> '''scan fabric'''
fact> '''show versions'''
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
fact> exit
$

===Using Single-Command Mode===
In single-command mode, a single command is passed to FACT as the program command arguments. FACT then runs the command, prints the results, and exits.

The following sample output shows the FACT single-command mode:

$ fact scan fabric
$ fact show versions
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
$

As a variant of single-command mode, the first word of the command, usually the verb, can be joined to the FACT name with a hyphen. The following sample output shows the FACT single-command mode:

$ '''fact-scan fabric'''
$ '''fact-show versions'''

To use shell completion to see available commands, join the FACT name with a hyphen, and enter the tab key:

$ '''fact'''-<TAB>

==Command-line Interface==

FACT looks for several environmental variables and accepts several command-line options.
This section describes the FACT command-line interface and shows how to use it.

===Command-line Options===

[[Using the CLI#Command-line Options|Table 2]] lists and describes the command-line options.

'''Table 2: Command-line Options'''

{| border="1" cellpadding="10" cellspacing="0"
!Option
!Description
|-
|'''-c''' ''file''
'''--config-file'''=''file''
|Reads primary configuration from the specified file.
|-
|'''--color'''='''always'''
|If tracing, specifies that the transcript is colorized, showing FACT requests in one color and the switch responses in another.
|-
|'''--color'''='''auto'''
|If tracing, specifies that the transcript is colorized only if the FACT standard output is a terminal. This behavior is the default.
|-
|'''--config-option'''=
''option''
|Adds or overrides a configuration option.
|-
|'''--credentials-from'''=''file''
|Adds credential information from the file.
See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|'''--guid-name'''=''guid''=''name''
|Adds a GUID name definition.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]] section.
|-
|'''--guid-names-
from'''=''file''
|Adds GUID name definitions from the specified file.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|'''-h
--help'''
|Prints a message describing messages.
|-
|'''--help-commands'''
|Lists FACT commands.
|-
|'''--managed-nodes-'''=''type: pattern''
|Adds a set of managed-nodes to those about which FACT is aware.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].

|-
|'''--managed-nodes-from'''=''file''
|Adds managed-nodes from the file.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|'''-s
--sequential'''
|Initiates sequential scan sessions to one managed node at a time. This option is helpful with the '''--trace''' command because output displays slower and more predictably. By default, FACT connects up to 50 managed nodes at a time during scans and installations. If sequential is specified, then FACT connects to one managed node at a time.
|-
|'''--subnet-manager'''=''domain name'' or ''IP address''
|Specifies the InfiniBand Subnet Manager host that FACT should use.
|-
|'''--trace''' and '''--sequential'''
|Runs sequential sessions to managed nodes and prints the session transcript.
|-
|'''-t
--trace'''
|By default, if '''--trace''' is not specified, then FACT will print the transcript of each session when that session is closed. If '''--trace''' is specified, FACT will print the transcript of each session as it occurs.
|-
|'''-v
--version'''
|Prints FACT version information and exits.
|}

===Environment Variables===
FACT uses environment variables to control the FACT configuration. [[Using the CLI#Environment Variables|Table 3]] lists and describes the FACT environment variables.

'''Table 3: Environment Variables'''

{| border="1" cellpadding="10" cellspacing="0"
!Variable
!Description
|-
|FACT_CONF
|Name of master configturation file.
See [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].
|-
|FACT_CREDENTIAL_FILES
|List of files that contain credentials, separated by colons, as shown in the following example:

:FACT_CREDENTIAL_FILES=/etc/fact/cred1:/etc/fact/cred2
:states that the files /etc/fact/cred1 and /etc/fact/cred2 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|FACT_GUID_NAMES
|List of GUID name definitions, separated by semicolons. Each definition has the form “GUID=name,” as shown in the following example:
:FACT_GUID_NAMES="00:1b:0d:0b:00:00:ca:a6=switchA;00:1b:0d:0b:00:00:ca:aa=switchB"
:defines switchA as the name for 00:1b:0d:0b:00:00:ca:a6 and switchB as the name for 00:1b:0d:0b:00:00:ca:aa

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_GUID_NAME_FILES
|List of files containing GUID name definitions, separated by colons, as shown in the following example:
:FACT_GUID_NAME_FILES=/tmp/guidnames1:/tmp/guidnames2 states that the files /tmp/guidnames1 and /tmp/guidnames1 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_MANAGED_NODES
|In-line list of managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODES="host=ibmg-r1-evil:SFSOS switch=209.165.200.225
:defines a host named ibmg-r1-evil and an SFS OS switch named 209.165.200.225

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|FACT_MANAGED_NODE_FILES
|List of files containing managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODE_FILES=/tmp/nodefile1:/tmp/nodefile2
:states that the files /tmp/nodefile1 and /tmp/nodefile2 contain managed node definitions

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|}

===Correcting Commands===

'''Note''': This feature will be functional at FCS.

The system response to command line-errors is different when you use the question mark (?) to obtain help for a command. In this case, the system repeats your input following the subsequent prompt for ease of editing, as shown in the following example:

fact> show interfce ?
^
% Error: Unrecognized command
fact> show interfce

===Editing the CLI===

Command-line editing lets you modify a command line command that you have just entered or a command line that you entered previously in the CLI session. The CLI supports a variety of ways to move about and edit the currently displayed command line. [[Using the CLI#Editing the CLI|Table 4]] lists and describes these options.

'''Table 4: Key Stroke Shortcuts'''

{| border="1" cellpadding="10" cellspacing="0"
!Key Strokes
!Description
|-
|'''Ctrl'''-'''A'''
|Moves the cursor to the beginning of the line.
|-
|'''Ctrl'''-'''B'''
|Moves the cursor to the left (backward) one character.
|-
|'''Ctrl'''-'''D'''
|Deletes the current character. Exits FACT if the current input line is empty.
|-
|'''Ctrl'''-'''E'''
|Moves the cursor to the end of the line.
|-
|'''Ctrl'''-'''F'''
|Moves the cursor to the right (forward) one character.
|-
|'''Ctrl'''-'''G'''
|Erases the current input line.
|-
|'''Ctrl'''-'''H'''
|Deletes the character to the left of the cursor, analogous to the Backspace key.
|-
|'''Ctrl'''-'''I'''
|Completes the current word, analogous to the Tab key.
|-
|'''Ctrl'''-'''J'''
|Accepts the current line.
|-
|'''Ctrl'''-'''K'''
|Deletes text from the cursor to the end of the line.
|-
|'''Ctrl'''-'''L'''
|Refreshes the input line.
|-
|'''Ctrl'''-'''M'''
|Accepts the current line, analogous to the Return key.
|-
|'''Ctrl'''-'''N'''
|Proceeds to the next line in the command history.
|-
|'''Ctrl'''-'''P'''
|Moves to the previous line in the command history.
|-
|'''Ctrl'''-'''T'''
|Transposes the current and previous characters.
|-
|'''Ctrl'''-'''U'''
|Deletes all text to the left of the cursor, back to the beginning of the line.
|-
|'''Ctrl'''-'''W'''
|Deletes the word to the left of the cursor.
|-
|'''Ctrl'''-'''Z'''
|Suspends the FACT.
|-
|'''Ctrl'''-'''Del'''
|Deletes the chatacter to the left of the cursor, analogous to the Delete key.
|-
|'''?'''
|Completes the current word.
|-
|'''Esc'''-'''[A'''
|Moves to the previous line in the command history.
|-
|'''Esc'''-'''[B'''
|Proceeds to the next line in the command history.
|-
|'''Esc'''-'''[C'''
|Moves the cursor to the right (forward) one character.
|-
|'''Esc'''-'''[D'''
|Moves the cursor to the left (backward) on character.
|-
|'''Esc'''-'''B'''
|Moves the cursor to the left (backward) one word.
|-
|'''Esc'''-'''C'''
|Capitalizes the word to the right of the cursor (forward).
|-
|'''Esc'''-'''D'''
|Deletes characters from the cursor through the end of the word.
|-
|'''Esc'''-'''F'''
|Moves the cursor right (forward) one word.
|-
|'''Esc'''-'''L'''
|Converts characters, from the cursor to the end of the word, to lowercase.
|-
|'''Esc'''-'''U'''
|Converts characters, from the cursor to the end of the word, to uppercase.
|-
|'''Esc'''-'''Ctrl'''-'''H'''
|Deletes the word to the left of the cursor.
|-
|'''Esc'''-'''Delete'''
|Deletes the word to the left of the cursor.
|-
|'''Down Arrow'''
|Proceeds to the next line in the command history.
|-
|'''Up Arrow'''
|Moves to the previous line in the command history.
|-
|'''Left Arrow'''
|Moves the cursor to the left (backward) one character.
|-
|'''Right Arrow'''
|Moves the cursor to the right (forward) one character.
|}

[[Category:Command Line Interface]]

About FACT Configuration Files

2008-05-24T00:23:17Z

Lorlando: /* Table 3: Parameters for Name-Value Pairs */

FACT uses four types of configuration files that you must create. This section describes the files.

==About Master Configuration Files==
FACT reads a master configuration file, which may specify other subsidiary configuration files. FACT searches for the master configuration file in the following files, using the first master configuration file that it finds:
:file specified by -c or --config-file command option
:file specified by FACT_CONF environment variable
:~/fact.conf (i.e., .fact.conf in user's home directory)
:/etc/fact.conf
:compiled-in defaults

The master configuration file contains name-value pairs, one per line. The parameter is separated from its value by a colon. Blank lines and comments that start with a pound character (#) are ignored.
The following parameters are permitted:
*repository: ''directory ''
:The directory where FACT stores its data.
*credential-file: ''file''
:A file containing credentials. (See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].)
*managed-nodes: ''type pattern''
:A managed-node definition. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*managed-node-file: ''file''
:A file containing managed node definitions. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*guid-name: ''guid name''
:A GUID name definition. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*guid-names-file: ''file''
:A file containing GUID name definitions. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*log-file: ''file''
:A log file created by the syslog and monitored by FACT.
*subnet-manager: ''domain name'' or ''IP address''
:The name of the Subnet Manager that FACT should use.
*ibportstate-host: ''host''
:The host on which FACT should run ibportstate to control switch ports. The default is localhost.
*ibportstate-command: ''path''
:The path to the '''ibportstate''' command on the ibportstate host. The default is ibportstate.
*ibspark-host: ''host''
:The host on which FACT should run ibspark. The default is ibspark.
*ibspark-command: ''path''
:The path to the '''ibspark''' command on the ibspark host. The default is localhost.

'''Note''': The credential-file, log-file, managed-nodes, managed-node-file, guid-name, and guid-names-file parameters may be repeated any number of times, and their effects are cumulative.

The following example shows one possible master configuration file:
repository: /var/local/db/fact
credential-file: /etc/fact/cred

For information about creating master configuration files, see [[Creating FACT Configuration Files#Creating a Master Configuration File|Creating a Master Configuration File]].

==About Managed Node Definitions Files==

A managed node is either a host or a managed switch. FACT must know about all of the managed nodes in any given network so that it can scan the network. Managed node definitions tell FACT the hostname or IP address and the type of each managed node. If managed nodes are not defined, FACT cannot connect to the switch management ports and collect the necessary information.

Names may be specified using node-list expansions, which are separated by commas, with no spaces. FACT has three types of expansions:

*Alternate—For example, leaf[A,C,D] expands to leafA, leafC, leafD.
*Range—For example, leaf[1-10] expands to leaf1, leaf2...leaf10.
*Combination of alternate and range—For example, rack[A,C]host[1-32] expands to rackAhost1, rackAhost1...rackChost32 (64 names total).

FACT managed-nodes have three types:
*SFSOS switch—Any Cisco Server Fabric Switch running Cisco SFS operating system software
*OEM switch—The Cisco SFS 7012 and Cisco SFS 7024
*host—A host running Unix

Managed-nodes can be listed directly in the master configuration file using the "managed-nodes" directive or in a separate file. A separate managed-nodes file has a node type and a list, as shown in the following example:

SFSOS switch switch[00-07]
host host-r[1-3,5]-[0-32]

The ranges in square brackets are expanded.

FACT looks in the following places for managed node definitions, with the highest priority sources listed first:

*Command options—managed-nodes=<type>:<pattern>
*Files specified by—managed-nodes-from=<file> options
*Definitions in the FACT_MANAGED_NODES environment variable
*Files in FACT_MANAGED_NODE_FILES environment variable (colon-separated list)
*Definitions in managed-nodes parameters in the master configuration file
*Files in managed-node-file parameters in the master configuration file

The managed node definitions file expands to six switch names: rackAleaf1 through rackAleaf3 and rackCleaf1 through rackCleaf3. It also expands to 64 host names: rackBcompute01 through rackDcompute32. If your managed-nodes follow this type of simple name scheme, you may place them into a master configuration file, as shown in the following example with managed-node parameters in the master configuration file:

managed-nodes: SFSOS switch rack[A,C]leaf[1-3]
managed-nodes: host rack[B,D]compute[01-32]

For information about creating a managed node definitions file, see [[Creating FACT Configuration Files#Creating a Separate Managed Node Definitions File (Optional)|Creating a Separate Managed Node Definitions File]].

==About Credentials Files==

For each managed node into which it logs, FACT must know which username and password to use. The credentials file provides this information. A credentials file consists of multiple stanzas. Each stanza begins with a device type line and is followed by several name-value pairs. Blank lines and comments starting with the pound sign (#) are ignored.

FACT looks in the following locations for credential files. The highest-priority locations, which are listed first, override definitions in later locations.

*Command options—credentials-from=file
*Files specified in FACT_CREDENTIAL_FILES environment variable (colon-separated list)
*Files specified in credentials-file parameters in the master configuration file
*Built-in defaults

FACT contains the following built-in default credentials:
:SFS OS switch
::method: ssh
::user: super
::password: super

:OEM switch
::method: ssh
::user: admin
::password: admin

:host
::method: ssh
::HSM-command: sudo /usr/local/topspin/sbin/ib_sm_cli || sudo /usr/sbin/ib_sm_cli
::vstat command: /usr/local/topspin/bin/vstat --verbose
::password: no default password exists

For information about creating a credentials file, see [[Creating FACT Configuration Files#Creating a Credentials File|Creating a Credentials File]].

===Device Types===
The device type line in the credentials file contains a device type, followed by a wildcard value that matches a set of device names. [[About FACT Configuration Files#Device Types|Table 1]] lists the device types that may appear in the device type line, and [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values.

=====Table 1: Device Types=====

{|border="1" cellpadding="10" cellspacing="0"
!Device Type
!Description
|-
|host
|A host running Unix
|-
|SFSOS switch
|A switch running SFS OS
|-
|OEM switch
|A Cisco OEM switch (SFS 7012 and SFS 7024 only)
|}

===Wildcard Values===
A wildcard is matched against managed-node names using a specific set of values. [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values against which the managed-node names are matched.

'''Note''': In the wildcard values represented below, where letters are used, actual wildcards can be either letters or numbers.

=====Table 2: Wildcard Values=====

{|border="1" cellpadding="10" cellspacing="0"
!Wildcard Value
!Description
|-
|*
|Matches any substring
|-
|?
|Matches any single character
|-
|[a,b]
|Matches either a or b
|-
|[a-b]
|Matches anything in the range of a through b, where a and b can be either letters or numbers
|-
|[a,c-e]
|Matches either a, c, d, or e
|}

===Name-Value Pairs===
The credentials file must contain name-value pairs that have specific, allowed parameters.
[[About FACT Configuration Files#Name-Value Pairs|Table 3]] lists the legal parameters for the name-value pairs in the credentials file.

=====Table 3: Parameters for Name-Value Pairs=====

{|border="1" cellpadding="10" cellspacing="0"
!Name-Value Pair
!Description
|-
|user
|Login username. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exits on the host.
Most users do use this parameter.
|-
|password
|Login password. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exists on other devices.
Most users do use this parameter.
|-
|method
|Method in which FACT connects to the device
Legal values are "SSH" to "direct." The default is "direct for the localhost and "SSH" for others.
Most users do not user this parameter.
|-
|port
|TCP port number to user for SSH. The default is 22.
Most users do not use this parameter
|-
|ssh-identity
|The SSH identity file to use for authentication. FACT does not use the default identity file, yet, SSH defaults to ~/.ssh/id_rsa or id_dsa.
Most Users do not use this parameter.
|-
|HSM-command
|The executable program to invoke the HSM CLI. The default is /usr/local/topspin/sbin/ib_sm_cli or /usr/sbin/ib_sm_cli.
Most users do not use this parameter.
|-
|vstat-command
|The '''vstat''' command, used to invoke vstat, includes the full path to the command and the verbose argument, which returns more information.The default is /usr/local/topspin/bin/vstat --verbose.

'''Note''': The vstate parameter is part of the Cisco host driver stack. If you are using OFED host drivers and your Cisco stack is installed in the normal way, you do not need to use the verbose parameter.

Most users do not use this parameter.
|}

'''Note''': The SSH method uses SSH to connect to the managed node. The direct method is only used to scan the host upon which FACT is running. (See [[How FACT Works#Understanding Secure Shell|Understanding Secure Shell]] for more information about SSH.)

The following example shows a possible credentials file:
: # This is a comment.
:SFSOS switch switch4*
::user: jsmith
::password: t0psekr1t
:host hsm-[1-3]
::method: ssh
::user: fact
::ssh-identity: ~/.ssh/id_rsa

===About GUID Name Definitions===

A GUID is a 64-bit number that is used to identify several types of InfiniBand components. Components that have GUIDs are Host Channel Adapters, switch chips, ports, and switch chassis. GUIDs are usually displayed as hexadecimal octets separated by colons, as shown in the following example:

00:02:c9:02:00:22:2a:c4

FACT uses GUID name definitions to associate GUIDs with names. FACT automatically builds its own associations between GUIDs and names. If FACT knows the host domain name or IP address, or the switch management port domain name or IP address, it uses this information as the switch name. If FACT does not know the GUID name of a switch, FACT refers to the switch by its system image GUID.

Optionally, you can augment and override the user-generated list and assign any name that you choose to a GUID by creating a GUID name definitions file in the master configuration file. FACT uses that GUID name when referring to that object and when showing information from a scan. Assigned GUID name definitions are most useful when you work with unmanaged switches. Without an assigned GUID name definition, there is no way for FACT to refer to an unmanaged switch except by its node GUID.

FACT looks in the following locations for GUID name definitions. Higher-priority sources are listed first in the following list, and they override lower priority sources:

*Command options—guid-name=''guid:name''
*Files specified by—guid-names-from=''file'' command options
*Definitions in the FACT_GUID_NAMES environment variable (comma-separated list)
*Files in FACT_GUID_NAME_FILES environment variable (colon-separated list)
*Definitions in guid-name parameters in the master configuration file
*Files in guid-names-file parameters in the master configuration file

The GUID name definition contains two pieces of information, the eight-byte GUID name and the name you assign to it, separated by spaces or commas. The following example shows a possible name definition file:

00:11:22:33:44:55:66:77 myswitch01
00:11:22:33:44:55:66:78 myswitch02
00:11:22:33:44:55:66:79 myswitch03
11:22:33:44:55:66:77:88 myhost01

If you do not want FACT to log in to each host in your cluster, and if FACT cannot determine the host names from the Subnet Manager, you can use GUID names to help FACT display useful names for your hosts.

'''Note''': You can also attach a name to a system image GUID, a chassis GUID, or a port GUID.

For information about creating GUID name definitions files, see [[Creating FACT Configuration Files#Creating a GUID Name Definition File (Optional)|Creating a GUID Name Definition File]].

FACT delete scans

2008-05-23T23:39:05Z

Lorlando:

To delete one or more scans from the repository, use the '''delete scans''' command.

::::::'''delete scans''' [''scans'']

'''Syntax Description'''
::::::{| cellpadding="10" cellspacing="0" border="1"
|''scans''
|Deletes the specified scan, the specified range of scans, or the latest scan performed.
|}

'''Command Default'''
::::::No default behavior or values.

'''Usage Guidelines'''
::::::Range numbers correspond to the numbers in the [[FACT show history|'''show history''']] command.

'''Examples'''
::::::The following example shows deleting scans 2 and 3 from the repository:

fact> '''show history'''

index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2008-04-17 10:44:02 PDT host01
2 fabric 2008-04-17 10:44:08 PDT host01
3 fabric 2008-04-17 10:44:14 PDT host01
4 Y tech-support 2008-04-17 10:44:47 PDT host01

fact> '''delete scans 2-3'''
Proceed with scan delete [Y/n]? '''yes'''

fact> '''show history'''

index current type date subnet-manager
----- ------- -------------- ------------------------- --------------
1 fabric 2008-04-17 10:44:02 PDT host01
2 Y tech-support 2008-04-17 10:44:47 PDT host01

'''Related Commands'''
::::::[[FACT show history|'''show history''']]
::::::[[FACT select|'''select''']]

About FACT Configuration Files

2008-05-23T23:19:14Z

Lorlando: /* Table 3: Parameters for Name-Value Pairs */

FACT uses four types of configuration files that you must create. This section describes the files.

==About Master Configuration Files==
FACT reads a master configuration file, which may specify other subsidiary configuration files. FACT searches for the master configuration file in the following files, using the first master configuration file that it finds:
:file specified by -c or --config-file command option
:file specified by FACT_CONF environment variable
:~/fact.conf (i.e., .fact.conf in user's home directory)
:/etc/fact.conf
:compiled-in defaults

The master configuration file contains name-value pairs, one per line. The parameter is separated from its value by a colon. Blank lines and comments that start with a pound character (#) are ignored.
The following parameters are permitted:
*repository: ''directory ''
:The directory where FACT stores its data.
*credential-file: ''file''
:A file containing credentials. (See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].)
*managed-nodes: ''type pattern''
:A managed-node definition. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*managed-node-file: ''file''
:A file containing managed node definitions. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*guid-name: ''guid name''
:A GUID name definition. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*guid-names-file: ''file''
:A file containing GUID name definitions. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*log-file: ''file''
:A log file created by the syslog and monitored by FACT.
*subnet-manager: ''domain name'' or ''IP address''
:The name of the Subnet Manager that FACT should use.
*ibportstate-host: ''host''
:The host on which FACT should run ibportstate to control switch ports. The default is localhost.
*ibportstate-command: ''path''
:The path to the '''ibportstate''' command on the ibportstate host. The default is ibportstate.
*ibspark-host: ''host''
:The host on which FACT should run ibspark. The default is ibspark.
*ibspark-command: ''path''
:The path to the '''ibspark''' command on the ibspark host. The default is localhost.

'''Note''': The credential-file, log-file, managed-nodes, managed-node-file, guid-name, and guid-names-file parameters may be repeated any number of times, and their effects are cumulative.

The following example shows one possible master configuration file:
repository: /var/local/db/fact
credential-file: /etc/fact/cred

For information about creating master configuration files, see [[Creating FACT Configuration Files#Creating a Master Configuration File|Creating a Master Configuration File]].

==About Managed Node Definitions Files==

A managed node is either a host or a managed switch. FACT must know about all of the managed nodes in any given network so that it can scan the network. Managed node definitions tell FACT the hostname or IP address and the type of each managed node. If managed nodes are not defined, FACT cannot connect to the switch management ports and collect the necessary information.

Names may be specified using node-list expansions, which are separated by commas, with no spaces. FACT has three types of expansions:

*Alternate—For example, leaf[A,C,D] expands to leafA, leafC, leafD.
*Range—For example, leaf[1-10] expands to leaf1, leaf2...leaf10.
*Combination of alternate and range—For example, rack[A,C]host[1-32] expands to rackAhost1, rackAhost1...rackChost32 (64 names total).

FACT managed-nodes have three types:
*SFSOS switch—Any Cisco Server Fabric Switch running Cisco SFS operating system software
*OEM switch—The Cisco SFS 7012 and Cisco SFS 7024
*host—A host running Unix

Managed-nodes can be listed directly in the master configuration file using the "managed-nodes" directive or in a separate file. A separate managed-nodes file has a node type and a list, as shown in the following example:

SFSOS switch switch[00-07]
host host-r[1-3,5]-[0-32]

The ranges in square brackets are expanded.

FACT looks in the following places for managed node definitions, with the highest priority sources listed first:

*Command options—managed-nodes=<type>:<pattern>
*Files specified by—managed-nodes-from=<file> options
*Definitions in the FACT_MANAGED_NODES environment variable
*Files in FACT_MANAGED_NODE_FILES environment variable (colon-separated list)
*Definitions in managed-nodes parameters in the master configuration file
*Files in managed-node-file parameters in the master configuration file

The managed node definitions file expands to six switch names: rackAleaf1 through rackAleaf3 and rackCleaf1 through rackCleaf3. It also expands to 64 host names: rackBcompute01 through rackDcompute32. If your managed-nodes follow this type of simple name scheme, you may place them into a master configuration file, as shown in the following example with managed-node parameters in the master configuration file:

managed-nodes: SFSOS switch rack[A,C]leaf[1-3]
managed-nodes: host rack[B,D]compute[01-32]

For information about creating a managed node definitions file, see [[Creating FACT Configuration Files#Creating a Separate Managed Node Definitions File (Optional)|Creating a Separate Managed Node Definitions File]].

==About Credentials Files==

For each managed node into which it logs, FACT must know which username and password to use. The credentials file provides this information. A credentials file consists of multiple stanzas. Each stanza begins with a device type line and is followed by several name-value pairs. Blank lines and comments starting with the pound sign (#) are ignored.

FACT looks in the following locations for credential files. The highest-priority locations, which are listed first, override definitions in later locations.

*Command options—credentials-from=file
*Files specified in FACT_CREDENTIAL_FILES environment variable (colon-separated list)
*Files specified in credentials-file parameters in the master configuration file
*Built-in defaults

FACT contains the following built-in default credentials:
:SFS OS switch
::method: ssh
::user: super
::password: super

:OEM switch
::method: ssh
::user: admin
::password: admin

:host
::method: ssh
::HSM-command: sudo /usr/local/topspin/sbin/ib_sm_cli \ || sudo /usr/sbin/ib_sm_cli
::vstat command: /usr/local/topspin/bin/vstat --verbose
::password: no default password exists

For information about creating a credentials file, see [[Creating FACT Configuration Files#Creating a Credentials File|Creating a Credentials File]].

===Device Types===
The device type line in the credentials file contains a device type, followed by a wildcard value that matches a set of device names. [[About FACT Configuration Files#Device Types|Table 1]] lists the device types that may appear in the device type line, and [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values.

=====Table 1: Device Types=====

{|border="1" cellpadding="10" cellspacing="0"
!Device Type
!Description
|-
|host
|A host running Unix
|-
|SFSOS switch
|A switch running SFS OS
|-
|OEM switch
|A Cisco OEM switch (SFS 7012 and SFS 7024 only)
|}

===Wildcard Values===
A wildcard is matched against managed-node names using a specific set of values. [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values against which the managed-node names are matched.

'''Note''': In the wildcard values represented below, where letters are used, actual wildcards can be either letters or numbers.

=====Table 2: Wildcard Values=====

{|border="1" cellpadding="10" cellspacing="0"
!Wildcard Value
!Description
|-
|*
|Matches any substring
|-
|?
|Matches any single character
|-
|[a,b]
|Matches either a or b
|-
|[a-b]
|Matches anything in the range of a through b, where a and b can be either letters or numbers
|-
|[a,c-e]
|Matches either a, c, d, or e
|}

===Name-Value Pairs===
The credentials file must contain name-value pairs that have specific, allowed parameters.
[[About FACT Configuration Files#Name-Value Pairs|Table 3]] lists the legal parameters for the name-value pairs in the credentials file.

=====Table 3: Parameters for Name-Value Pairs=====

{|border="1" cellpadding="10" cellspacing="0"
!Name-Value Pair
!Description
|-
|user
|Login username. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exits on the host.
Most users do use this parameter.
|-
|password
|Login password. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exists on other devices.
Most users do use this parameter.
|-
|method
|Method in which FACT connects to the device
Legal values are "SSH" to "direct." The default is "direct for the localhost and "SSH" for others.
Most users do not user this parameter.
|-
|port
|TCP port number to user for SSH. The default is 22.
Most users do not use this parameter
|-
|ssh-identity
|The SSH identity file to use for authentication. FACT does not use the default identity file, yet, SSH defaults to ~/.ssh/id_rsa or id_dsa.
Most Users do not use this parameter.
|-
|HSM-command
|The executable program to invoke the HSM CLI. The default is /usr/local/topspin/sbin/ib_sm_cli or /usr/sbin/ib_sm_cli.
Most users do not use this parameter.
|-
|vstat-command
|The '''vstat''' command, used to invoke vstat, includes the full path to the command and the verbose argument, which returns more information.The default is /usr/local/topspin/bin/vstat --verbose.

'''Note''': The vstate parameter is part of the Cisco host driver stack. If you are using OFED host drivers and your Cisco stack is installed in the normal way, you do not need to use the verbose parameter.

Most users do not use this parameter.
|}

'''Note''': The SSH method uses SSH to connect to the managed node. The direct method is only used to scan the host upon which FACT is running. (See [[How FACT Works#Understanding Secure Shell|Understanding Secure Shell]] for more information about SSH.)

The following example shows a possible credentials file:
:(#) This is a comment.
:SFSOS switch switch4*
::user: jsmith
::password: t0psekr1t
:host hsm-[1-3]
::method: ssh
::user: fact
::ssh-identity: ~/.ssh/id_rsa

===About GUID Name Definitions===

A GUID is a 64-bit number that is used to identify several types of InfiniBand components. Components that have GUIDs are Host Channel Adapters, switch chips, ports, and switch chassis. GUIDs are usually displayed as hexadecimal octets separated by colons, as shown in the following example:

00:02:c9:02:00:22:2a:c4

FACT uses GUID name definitions to associate GUIDs with names. FACT automatically builds its own associations between GUIDs and names. If FACT knows the host domain name or IP address, or the switch management port domain name or IP address, it uses this information as the switch name. If FACT does not know the GUID name of a switch, FACT refers to the switch by its system image GUID.

Optionally, you can augment and override the user-generated list and assign any name that you choose to a GUID by creating a GUID name definitions file in the master configuration file. FACT uses that GUID name when referring to that object and when showing information from a scan. Assigned GUID name definitions are most useful when you work with unmanaged switches. Without an assigned GUID name definition, there is no way for FACT to refer to an unmanaged switch except by its node GUID.

FACT looks in the following locations for GUID name definitions. Higher-priority sources are listed first in the following list, and they override lower priority sources:

*Command options—guid-name=''guid:name''
*Files specified by—guid-names-from=''file'' command options
*Definitions in the FACT_GUID_NAMES environment variable (comma-separated list)
*Files in FACT_GUID_NAME_FILES environment variable (colon-separated list)
*Definitions in guid-name parameters in the master configuration file
*Files in guid-names-file parameters in the master configuration file

The GUID name definition contains two pieces of information, the eight-byte GUID name and the name you assign to it, separated by spaces or commas. The following example shows a possible name definition file:

00:11:22:33:44:55:66:77 myswitch01
00:11:22:33:44:55:66:78 myswitch02
00:11:22:33:44:55:66:79 myswitch03
11:22:33:44:55:66:77:88 myhost01

If you do not want FACT to log in to each host in your cluster, and if FACT cannot determine the host names from the Subnet Manager, you can use GUID names to help FACT display useful names for your hosts.

'''Note''': You can also attach a name to a system image GUID, a chassis GUID, or a port GUID.

For information about creating GUID name definitions files, see [[Creating FACT Configuration Files#Creating a GUID Name Definition File (Optional)|Creating a GUID Name Definition File]].

About FACT Configuration Files

2008-05-23T23:14:58Z

Lorlando: /* Table 1: Device Types */

FACT uses four types of configuration files that you must create. This section describes the files.

==About Master Configuration Files==
FACT reads a master configuration file, which may specify other subsidiary configuration files. FACT searches for the master configuration file in the following files, using the first master configuration file that it finds:
:file specified by -c or --config-file command option
:file specified by FACT_CONF environment variable
:~/fact.conf (i.e., .fact.conf in user's home directory)
:/etc/fact.conf
:compiled-in defaults

The master configuration file contains name-value pairs, one per line. The parameter is separated from its value by a colon. Blank lines and comments that start with a pound character (#) are ignored.
The following parameters are permitted:
*repository: ''directory ''
:The directory where FACT stores its data.
*credential-file: ''file''
:A file containing credentials. (See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].)
*managed-nodes: ''type pattern''
:A managed-node definition. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*managed-node-file: ''file''
:A file containing managed node definitions. (See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].)
*guid-name: ''guid name''
:A GUID name definition. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*guid-names-file: ''file''
:A file containing GUID name definitions. (See [[About FACT Configuration Files#About GUID Name Definitions|About GUID Name Definitions]].)
*log-file: ''file''
:A log file created by the syslog and monitored by FACT.
*subnet-manager: ''domain name'' or ''IP address''
:The name of the Subnet Manager that FACT should use.
*ibportstate-host: ''host''
:The host on which FACT should run ibportstate to control switch ports. The default is localhost.
*ibportstate-command: ''path''
:The path to the '''ibportstate''' command on the ibportstate host. The default is ibportstate.
*ibspark-host: ''host''
:The host on which FACT should run ibspark. The default is ibspark.
*ibspark-command: ''path''
:The path to the '''ibspark''' command on the ibspark host. The default is localhost.

'''Note''': The credential-file, log-file, managed-nodes, managed-node-file, guid-name, and guid-names-file parameters may be repeated any number of times, and their effects are cumulative.

The following example shows one possible master configuration file:
repository: /var/local/db/fact
credential-file: /etc/fact/cred

For information about creating master configuration files, see [[Creating FACT Configuration Files#Creating a Master Configuration File|Creating a Master Configuration File]].

==About Managed Node Definitions Files==

A managed node is either a host or a managed switch. FACT must know about all of the managed nodes in any given network so that it can scan the network. Managed node definitions tell FACT the hostname or IP address and the type of each managed node. If managed nodes are not defined, FACT cannot connect to the switch management ports and collect the necessary information.

Names may be specified using node-list expansions, which are separated by commas, with no spaces. FACT has three types of expansions:

*Alternate—For example, leaf[A,C,D] expands to leafA, leafC, leafD.
*Range—For example, leaf[1-10] expands to leaf1, leaf2...leaf10.
*Combination of alternate and range—For example, rack[A,C]host[1-32] expands to rackAhost1, rackAhost1...rackChost32 (64 names total).

FACT managed-nodes have three types:
*SFSOS switch—Any Cisco Server Fabric Switch running Cisco SFS operating system software
*OEM switch—The Cisco SFS 7012 and Cisco SFS 7024
*host—A host running Unix

Managed-nodes can be listed directly in the master configuration file using the "managed-nodes" directive or in a separate file. A separate managed-nodes file has a node type and a list, as shown in the following example:

SFSOS switch switch[00-07]
host host-r[1-3,5]-[0-32]

The ranges in square brackets are expanded.

FACT looks in the following places for managed node definitions, with the highest priority sources listed first:

*Command options—managed-nodes=<type>:<pattern>
*Files specified by—managed-nodes-from=<file> options
*Definitions in the FACT_MANAGED_NODES environment variable
*Files in FACT_MANAGED_NODE_FILES environment variable (colon-separated list)
*Definitions in managed-nodes parameters in the master configuration file
*Files in managed-node-file parameters in the master configuration file

The managed node definitions file expands to six switch names: rackAleaf1 through rackAleaf3 and rackCleaf1 through rackCleaf3. It also expands to 64 host names: rackBcompute01 through rackDcompute32. If your managed-nodes follow this type of simple name scheme, you may place them into a master configuration file, as shown in the following example with managed-node parameters in the master configuration file:

managed-nodes: SFSOS switch rack[A,C]leaf[1-3]
managed-nodes: host rack[B,D]compute[01-32]

For information about creating a managed node definitions file, see [[Creating FACT Configuration Files#Creating a Separate Managed Node Definitions File (Optional)|Creating a Separate Managed Node Definitions File]].

==About Credentials Files==

For each managed node into which it logs, FACT must know which username and password to use. The credentials file provides this information. A credentials file consists of multiple stanzas. Each stanza begins with a device type line and is followed by several name-value pairs. Blank lines and comments starting with the pound sign (#) are ignored.

FACT looks in the following locations for credential files. The highest-priority locations, which are listed first, override definitions in later locations.

*Command options—credentials-from=file
*Files specified in FACT_CREDENTIAL_FILES environment variable (colon-separated list)
*Files specified in credentials-file parameters in the master configuration file
*Built-in defaults

FACT contains the following built-in default credentials:
:SFS OS switch
::method: ssh
::user: super
::password: super

:OEM switch
::method: ssh
::user: admin
::password: admin

:host
::method: ssh
::HSM-command: sudo /usr/local/topspin/sbin/ib_sm_cli \ || sudo /usr/sbin/ib_sm_cli
::vstat command: /usr/local/topspin/bin/vstat --verbose
::password: no default password exists

For information about creating a credentials file, see [[Creating FACT Configuration Files#Creating a Credentials File|Creating a Credentials File]].

===Device Types===
The device type line in the credentials file contains a device type, followed by a wildcard value that matches a set of device names. [[About FACT Configuration Files#Device Types|Table 1]] lists the device types that may appear in the device type line, and [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values.

=====Table 1: Device Types=====

{|border="1" cellpadding="10" cellspacing="0"
!Device Type
!Description
|-
|host
|A host running Unix
|-
|SFSOS switch
|A switch running SFS OS
|-
|OEM switch
|A Cisco OEM switch (SFS 7012 and SFS 7024 only)
|}

===Wildcard Values===
A wildcard is matched against managed-node names using a specific set of values. [[About FACT Configuration Files#Wildcard Values|Table 2]] lists the wildcard values against which the managed-node names are matched.

'''Note''': In the wildcard values represented below, where letters are used, actual wildcards can be either letters or numbers.

=====Table 2: Wildcard Values=====

{|border="1" cellpadding="10" cellspacing="0"
!Wildcard Value
!Description
|-
|*
|Matches any substring
|-
|?
|Matches any single character
|-
|[a,b]
|Matches either a or b
|-
|[a-b]
|Matches anything in the range of a through b, where a and b can be either letters or numbers
|-
|[a,c-e]
|Matches either a, c, d, or e
|}

===Name-Value Pairs===
The credentials file must contain name-value pairs that have specific, allowed parameters.
[[About FACT Configuration Files#Name-Value Pairs|Table 3]] lists the legal parameters for the name-value pairs in the credentials file.

=====Table 3: Parameters for Name-Value Pairs=====

{|border="1" cellpadding="10" cellspacing="0"
!Name-Value Pair
!Description
|-
|user
|Login username. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exits on the host.
Most users do use this parameter.
|-
|password
|Login password. The default is "super" on SFS OS switches and "admin" on OEM switches. No default exists on other devices.
Most users do use this parameter.
|-
|method
|Method in which FACT connects to the device
Legal values are "SSH" to "direct." The default is "direct for the localhost and "SSH" for others.
Most users do not user this parameter.
|-
|port
|TCP port number to user for SSH. The default is 22.
Most users do not use this parameter
|-
|ssh-identity
|The SSH identity file to use for authentication. FACT does not use the default identity file, yet, SSH defaults to ~/.ssh/id_rsa or id_dsa.
Most Users do not use this parameter.
|-
|HSM-command
|The executable program to invoke the HSM CLI. The default is /usr/local/topspin/sbin/ib_sm_cli or /usr/sbin/ib_sm_cli.
Most users do not use this parameter.
|-
|vstat-command
|The '''vstat''' command, used to invoke vstat, includes the full path to the command and the verbose argument, which returns more information.The default is /usr/local/topspin/bin/vstat --verbose.

'''Note''': The vstate parameter is part of the Cisco host driver stack. If you are using OFED host drivers and your Cisco stack is installed in the normal way, you do not need to use the verbose parameter.

Most users do not use this parameter.
|}

'''Note''': The SSH method uses SSH to connect to the managed node. The direct method is only used to scan the host upon which FACT is running. (See [[How FACT Works#Understanding Secure Shell|Understanding Secure Shell]] for more information about SSH.)

The following example shows a possible credentials file:
:(#) This is a comment.
:SFSOS switch switch4*
::user: jsmith
::password: t0psekr1t
:host hsm-[1-3]
::method: ssh
::user: fact
::ssh-identity: ~/.ssh/id_rsa

FACT looks in the following locations for credentials files. The highest-priority locations, which are listed first, override definitions in later locations.
*Command options—credentials-from=file
*Files specified in FACT_CREDENTIAL_FILES environment variable (colon-separated list)
*Files specified in credentials-file parameters in the master configuration file
*Built-in defaults

===About GUID Name Definitions===

A GUID is a 64-bit number that is used to identify several types of InfiniBand components. Components that have GUIDs are Host Channel Adapters, switch chips, ports, and switch chassis. GUIDs are usually displayed as hexadecimal octets separated by colons, as shown in the following example:

00:02:c9:02:00:22:2a:c4

FACT uses GUID name definitions to associate GUIDs with names. FACT automatically builds its own associations between GUIDs and names. If FACT knows the host domain name or IP address, or the switch management port domain name or IP address, it uses this information as the switch name. If FACT does not know the GUID name of a switch, FACT refers to the switch by its system image GUID.

Optionally, you can augment and override the user-generated list and assign any name that you choose to a GUID by creating a GUID name definitions file in the master configuration file. FACT uses that GUID name when referring to that object and when showing information from a scan. Assigned GUID name definitions are most useful when you work with unmanaged switches. Without an assigned GUID name definition, there is no way for FACT to refer to an unmanaged switch except by its node GUID.

FACT looks in the following locations for GUID name definitions. Higher-priority sources are listed first in the following list, and they override lower priority sources:

*Command options—guid-name=''guid:name''
*Files specified by—guid-names-from=''file'' command options
*Definitions in the FACT_GUID_NAMES environment variable (comma-separated list)
*Files in FACT_GUID_NAME_FILES environment variable (colon-separated list)
*Definitions in guid-name parameters in the master configuration file
*Files in guid-names-file parameters in the master configuration file

The GUID name definition contains two pieces of information, the eight-byte GUID name and the name you assign to it, separated by spaces or commas. The following example shows a possible name definition file:

00:11:22:33:44:55:66:77 myswitch01
00:11:22:33:44:55:66:78 myswitch02
00:11:22:33:44:55:66:79 myswitch03
11:22:33:44:55:66:77:88 myhost01

If you do not want FACT to log in to each host in your cluster, and if FACT cannot determine the host names from the Subnet Manager, you can use GUID names to help FACT display useful names for your hosts.

'''Note''': You can also attach a name to a system image GUID, a chassis GUID, or a port GUID.

For information about creating GUID name definitions files, see [[Creating FACT Configuration Files#Creating a GUID Name Definition File (Optional)|Creating a GUID Name Definition File]].

How FACT Works

2008-05-23T23:11:11Z

Lorlando: /* Hardware and Software Compatibility */

= Scanning and Reporting =
FACT scans a subnet by logging in to the management ports of many switches, finding the master Subnet Manager (or the host Subnet Manager if the host is listed as a managed node), and interrogating it through the CLI. FACT then constructs a view of the network topology and saves it to a file to answer later queries. If presented with a network with no Subnet Managers or with several master Subnet Managers, FACT has reduced function, but it can report the location of the master and standby Subnet Managers. For more information about the Subnet Manager, see the "Understanding the Subnet Manager" section.

FACT has a set of queries to scan the fabric, similar to those in the Subnet Manager, where it can show which switches are in the network, which ports are active, how they are connected, and so on. By reporting this information, FACT differentiates itself from the Subnet Manager show commands because it reports both at the chip level (InfiniBand nodes and ports) and at the chassis level (chassis, slots, and external ports).

Along with scanning the fabric for information about connectivity, FACT can perform a thorough technical-support scan, in which it collects voluminous diagnostic information from every SFS OS switch, collecting information that Cisco TAC or engineering can use to diagnose problems remotely. For more information about scans, see [[FACT Scanning#Scanning|Scanning]].

= Repository =

All information that FACT collects is stored in its repository, which is a directory in the file system. The FACT repository contains the following items:
* Results of all scans
* A log of analysis errors
* Transcripts of all switch CLI sessions
* A "last-known neighbor" map used to remember neighbor relationships after links go down
* A pointer to the current scan
The repository also maintains the notion of a "current scan." Because queries are always performed against the current scan, the repository has a history mechanism that allows the current scan to be rolled back to an earlier version. For more information about the repository, see [[FACT Scanning#Maintaining the Repository|Maintaining the Repository]].

= Connections =

The scanning function requires that FACT be able to log in to each switch in the network. Also, if you are using HSM, FACT must be able to log in to each host that is running the High-Performance Subnet Manager (HSM).
FACT has a variety of ways to connect:
* Using SSH to connect to a switch management port
* Using SSH to log in to a host running HSM and starting the HSM CLI
* Using SSH to log in to a host running HSM and running the HSM CLI directly as a subprocess if HSM and FACT are on the same host
The credential files control which mechanisms FACT uses for each managed node. For more information about credentials files, see [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].

= Network Maintenance =

FACT can display the firmware versions on switches in a network and perform firmware updates, either on individual switches or on multiple switches simultaneously.
FACT can also control ports. FACT can enable or disable one or several ports, individually, and change their width and speed. Using this port-control capability is more desirable than using the existing switch CLI because FACT is a single point of control. FACT allows the port to be specified by either the chassis or the chip location.

= Hardware and Software Compatibility =

FACT runs on a Linux host and requires the following supported software distributions:
* RedHat Enterprise Linux, Version 4 or 5, or SUSE Linux Enterprise Server Distribution, Version 9 or 10
* Python, Version 2.3 or later
FACT can log in to Cisco Server Fabric Switches that run Cisco SFS OS, to OEM switches (Cisco SFS 7012 and Cisco SFS 7024), and to Unix/Linux-based hosts, including those that run the host-based Subnet Manager. FACT can also monitor and control unmanaged switches to a limited extent by using in-band InfiniBand messages.
FACT uses the ibspark tool to upgrade firmware on unmanaged switches. FACT uses the ibportstate tool to control ports. These tools must be installed and available on a Linux host that is directly connected to the InfiniBand network and that FACT can log in to through SSH. FACT performs all other operations through IP to the management ports on a device, so it can run on any network-connected host.
FACT can optionally use configurations that map node GUIDs and system image GUIDs to user-specified names. This option is especially useful when working with unmanaged switches because unmanaged switches do not have IP addresses or other identifiers; their only identifiers are their node GUIDs. However, GUID names can be used for any switch or channel adapter.

= Understanding the Subnet Manager =

FACT works closely with the Subnet Manager to understand the network fabric because the Subnet Manager configures and maintains fabric operations. The Subnet Manager is the central repository of all information that is required to set up and bring up the InfiniBand fabric.
The master Subnet Manager does the following:
* Discovers the fabric topology
* Discovers end nodes
* Configures switches and end nodes with their parameters, such as the following:
** LIDs
** GUIDs
** Partition Keys (P_Keys)
* Configures switch forwarding tables
* Receives traps from Subnet Management Agents (SMAs)
* Sweeps the subnet, discovering topology changes and managing changes as nodes are added and deleted
A network may contain multiple Subnet Managers acting as standbys, but it may contain only one master Subnet Manager.

= Understanding Secure Shell =

Secure Shell (SSH) is a network protocol that provides a secure remote access connection to network devices. Cisco FACT uses SSH to provide secure communication from network computers to the Cisco SFS OS CLI.

How FACT Works

2008-05-23T23:01:23Z

Lorlando: /* Connections */

= Scanning and Reporting =
FACT scans a subnet by logging in to the management ports of many switches, finding the master Subnet Manager (or the host Subnet Manager if the host is listed as a managed node), and interrogating it through the CLI. FACT then constructs a view of the network topology and saves it to a file to answer later queries. If presented with a network with no Subnet Managers or with several master Subnet Managers, FACT has reduced function, but it can report the location of the master and standby Subnet Managers. For more information about the Subnet Manager, see the "Understanding the Subnet Manager" section.

FACT has a set of queries to scan the fabric, similar to those in the Subnet Manager, where it can show which switches are in the network, which ports are active, how they are connected, and so on. By reporting this information, FACT differentiates itself from the Subnet Manager show commands because it reports both at the chip level (InfiniBand nodes and ports) and at the chassis level (chassis, slots, and external ports).

Along with scanning the fabric for information about connectivity, FACT can perform a thorough technical-support scan, in which it collects voluminous diagnostic information from every SFS OS switch, collecting information that Cisco TAC or engineering can use to diagnose problems remotely. For more information about scans, see [[FACT Scanning#Scanning|Scanning]].

= Repository =

All information that FACT collects is stored in its repository, which is a directory in the file system. The FACT repository contains the following items:
* Results of all scans
* A log of analysis errors
* Transcripts of all switch CLI sessions
* A "last-known neighbor" map used to remember neighbor relationships after links go down
* A pointer to the current scan
The repository also maintains the notion of a "current scan." Because queries are always performed against the current scan, the repository has a history mechanism that allows the current scan to be rolled back to an earlier version. For more information about the repository, see [[FACT Scanning#Maintaining the Repository|Maintaining the Repository]].

= Connections =

The scanning function requires that FACT be able to log in to each switch in the network. Also, if you are using HSM, FACT must be able to log in to each host that is running the High-Performance Subnet Manager (HSM).
FACT has a variety of ways to connect:
* Using SSH to connect to a switch management port
* Using SSH to log in to a host running HSM and starting the HSM CLI
* Using SSH to log in to a host running HSM and running the HSM CLI directly as a subprocess if HSM and FACT are on the same host
The credential files control which mechanisms FACT uses for each managed node. For more information about credentials files, see [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].

= Network Maintenance =

FACT can display the firmware versions on switches in a network and perform firmware updates, either on individual switches or on multiple switches simultaneously.
FACT can also control ports. FACT can enable or disable one or several ports, individually, and change their width and speed. Using this port-control capability is more desirable than using the existing switch CLI because FACT is a single point of control. FACT allows the port to be specified by either the chassis or the chip location.

= Hardware and Software Compatibility =

FACT runs on a Linux host and requires the following supported software distributions:
* RedHat Enterprise Linux, Version 4 or 5, or SUSE Linux Enterprise Server Distribution, Version 9 or 10
* Python, Version 2.3 or later
FACT can log in to Cisco Server Fabric Switches that run Cisco SFS OS, to OEM switches from QLogic (Cisco SFS 7012 and Cisco SFS 7024), and to Unix/Linux-based hosts, including those that run the host-based Subnet Manager. FACT can also monitor and control unmanaged switches to a limited extent by using in-band InfiniBand messages.
FACT uses the ibspark tool to upgrade firmware on unmanaged switches. FACT uses the ibportstate tool to control ports. These tools must be installed and available on a Linux host that is directly connected to the InfiniBand network and that FACT can log in to through SSH. FACT performs all other operations through IP to the management ports on a device, so it can run on any network-connected host.
FACT can optionally use configurations that map node GUIDs and system image GUIDs to user-specified names. This option is especially useful when working with unmanaged switches because unmanaged switches do not have IP addresses or other identifiers; their only identifiers are their node GUIDs. However, GUID names can be used for any switch or channel adapter.

= Understanding the Subnet Manager =

FACT works closely with the Subnet Manager to understand the network fabric because the Subnet Manager configures and maintains fabric operations. The Subnet Manager is the central repository of all information that is required to set up and bring up the InfiniBand fabric.
The master Subnet Manager does the following:
* Discovers the fabric topology
* Discovers end nodes
* Configures switches and end nodes with their parameters, such as the following:
** LIDs
** GUIDs
** Partition Keys (P_Keys)
* Configures switch forwarding tables
* Receives traps from Subnet Management Agents (SMAs)
* Sweeps the subnet, discovering topology changes and managing changes as nodes are added and deleted
A network may contain multiple Subnet Managers acting as standbys, but it may contain only one master Subnet Manager.

= Understanding Secure Shell =

Secure Shell (SSH) is a network protocol that provides a secure remote access connection to network devices. Cisco FACT uses SSH to provide secure communication from network computers to the Cisco SFS OS CLI.

How FACT Works

2008-05-23T22:41:31Z

Lorlando: /* Scanning and Reporting */

= Scanning and Reporting =
FACT scans a subnet by logging in to the management ports of many switches, finding the master Subnet Manager (or the host Subnet Manager if the host is listed as a managed node), and interrogating it through the CLI. FACT then constructs a view of the network topology and saves it to a file to answer later queries. If presented with a network with no Subnet Managers or with several master Subnet Managers, FACT has reduced function, but it can report the location of the master and standby Subnet Managers. For more information about the Subnet Manager, see the "Understanding the Subnet Manager" section.

FACT has a set of queries to scan the fabric, similar to those in the Subnet Manager, where it can show which switches are in the network, which ports are active, how they are connected, and so on. By reporting this information, FACT differentiates itself from the Subnet Manager show commands because it reports both at the chip level (InfiniBand nodes and ports) and at the chassis level (chassis, slots, and external ports).

Along with scanning the fabric for information about connectivity, FACT can perform a thorough technical-support scan, in which it collects voluminous diagnostic information from every SFS OS switch, collecting information that Cisco TAC or engineering can use to diagnose problems remotely. For more information about scans, see [[FACT Scanning#Scanning|Scanning]].

= Repository =

All information that FACT collects is stored in its repository, which is a directory in the file system. The FACT repository contains the following items:
* Results of all scans
* A log of analysis errors
* Transcripts of all switch CLI sessions
* A "last-known neighbor" map used to remember neighbor relationships after links go down
* A pointer to the current scan
The repository also maintains the notion of a "current scan." Because queries are always performed against the current scan, the repository has a history mechanism that allows the current scan to be rolled back to an earlier version. For more information about the repository, see [[FACT Scanning#Maintaining the Repository|Maintaining the Repository]].

= Connections =

The scanning function requires that FACT be able to log in to each switch in the network. Also, if you are using HSM, FACT must be able to log in to each host that is running HSM>
Fact has a variety of ways to connect:
* Using SSH to connect to a switch management port
* Using SSH to log in to a host running HSM and starting the HSM CLI
* Using SSH to log in to a host running HSM and running the HSM CLI directly as a subprocess if HSM and FACT are on the same host
The credential files control which mechanisms FACT uses for each managed node. For more information about credentials files, see [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].

= Network Maintenance =

FACT can display the firmware versions on switches in a network and perform firmware updates, either on individual switches or on multiple switches simultaneously.
FACT can also control ports. FACT can enable or disable one or several ports, individually, and change their width and speed. Using this port-control capability is more desirable than using the existing switch CLI because FACT is a single point of control. FACT allows the port to be specified by either the chassis or the chip location.

= Hardware and Software Compatibility =

FACT runs on a Linux host and requires the following supported software distributions:
* RedHat Enterprise Linux, Version 4 or 5, or SUSE Linux Enterprise Server Distribution, Version 9 or 10
* Python, Version 2.3 or later
FACT can log in to Cisco Server Fabric Switches that run Cisco SFS OS, to OEM switches from QLogic (Cisco SFS 7012 and Cisco SFS 7024), and to Unix/Linux-based hosts, including those that run the host-based Subnet Manager. FACT can also monitor and control unmanaged switches to a limited extent by using in-band InfiniBand messages.
FACT uses the ibspark tool to upgrade firmware on unmanaged switches. FACT uses the ibportstate tool to control ports. These tools must be installed and available on a Linux host that is directly connected to the InfiniBand network and that FACT can log in to through SSH. FACT performs all other operations through IP to the management ports on a device, so it can run on any network-connected host.
FACT can optionally use configurations that map node GUIDs and system image GUIDs to user-specified names. This option is especially useful when working with unmanaged switches because unmanaged switches do not have IP addresses or other identifiers; their only identifiers are their node GUIDs. However, GUID names can be used for any switch or channel adapter.

= Understanding the Subnet Manager =

FACT works closely with the Subnet Manager to understand the network fabric because the Subnet Manager configures and maintains fabric operations. The Subnet Manager is the central repository of all information that is required to set up and bring up the InfiniBand fabric.
The master Subnet Manager does the following:
* Discovers the fabric topology
* Discovers end nodes
* Configures switches and end nodes with their parameters, such as the following:
** LIDs
** GUIDs
** Partition Keys (P_Keys)
* Configures switch forwarding tables
* Receives traps from Subnet Management Agents (SMAs)
* Sweeps the subnet, discovering topology changes and managing changes as nodes are added and deleted
A network may contain multiple Subnet Managers acting as standbys, but it may contain only one master Subnet Manager.

= Understanding Secure Shell =

Secure Shell (SSH) is a network protocol that provides a secure remote access connection to network devices. Cisco FACT uses SSH to provide secure communication from network computers to the Cisco SFS OS CLI.

Using the CLI

2008-05-23T22:36:55Z

Lorlando: /* Command-line Options */

==Using FACT Command Arguments==

An argument is a text expression that denotes one or more objects in the fabric. Arguments are used as srguments to the FACT commands.

===Using Singular Arguments===

This section describes the syntax for each type of argument. [[Using the CLI#Using Singular Arguments|Table 1]] lists the argument syntax and the corresponding descriptions.

'''Table 1: Argument Syntax'''
{| border="1" cellpadding="10" cellspacing="0"
!Syntax
!Argument Description
|-
|''scan''
|Scans are numbered chronologically starting from 1. (1 is the oldest; N is the latest.) The latest scan can be specified as “latest.” The [[FACT show history|'''show history''']] command shows the number of each scan.
|-
|''file''
|A file or pathname is used by the FACT host platform.
|-
|''switch''
|A switch can be specified in one of the following ways:

*hostname or IP address of its management port, as specified in the managed-node definition. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
*chassis GUID, using the notation 00:11:22:33:44:55:66:77.
*given name of its chassis GUID (from guid name definition).
*description of one of its chips, prepended by “chassis,” as shown in the following example:

:chassis:00:11:22:33:44:55:66:77 (a node GUID)
|-
|''host''
|A host can be specified in one of the following ways:
*hostname or IP address, as specified in the managed-node definition.
*given name of its HCA node GUID (from guid name definitions).
*node GUID of its HCA, prepended by “chassis.”
|-
|''chassis''
|A chassis is either a host or a switch. Any of the previously listed notations for host or switch may be used.
|-
|''managed-node''
|A managed node is either a host or a switch. It must be specified exactly as it appears in the managed-node part of the configuration. See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|''chip''
|A chip is an InfiniBand switch chip or InfiniBand channel adapter chip. It may be specified in the following ways:
*node GUID.
*given name from the GUID name definitions.
*the notation ''switch/slot:index'', where switch is a switch name, as described above, slot is a slot number (decimal integer) in a switch, and ''index'' is a decimal number. FACT orders chips in a slot by the node GUID. FACT numbers chips from 1 to n, ordered by their node GUIDs, going in ascending order from lowest to highest.
|-
|''port''
|A port may be specified as a port GUID, relative to a chassis or relative to a chip. As a port GUID, it is specified in eight hexadecimal octets separated by colons, as shown in the following example:
:00:02:c9:02:00:22:2a:c8

'''Note''': Most switch chips do not have port GUIDs.

Chassis-relative form has the '''syntax switch/slot/ext-number'', where ''ext-number'' is the external port number. ''Switch'' has any of the previously listed forms, as shown in the following example:
:switch01/2/3
:(port 3 on slot 2 of chassis switch01)

'''Note''': Internal chips can be specified in chip-relative syntax only.

Chip-relative form has the syntax ''chip/internal-number'', where chip is an InfiniBand chip as previously listed, and ''internal number'' is the port number on the chip, as shown in the following examples:
:switch01/2:3/4
:(chip port 4 on chip 3 of the card in slot 2 of chassis switch01)
:00:02:c9:02:00:22:2a:c4/4
:(chip port 4 on the chip with the given GUID)
|-
|''LID''
|A LID is a decimal integer.
|-
|''MLID''
|A multicast LID is a decimal integer.
|}

===Using Plural Arguments===

Many of the commands in FACT can accept plural arguments. The plurals can be built in several ways. Several alternatives can be separated by commas, with no spaces, as shown in the following example:
:switch01,switch02
Each alternative may contain one or more ranges. A range is surrounded by square brackets and contains one or more comma-separated alternatives. Each alternative may be a single value or a hyphen-separated range of values, as shown in the following example:
:rack[A-C,E]-host[01-10]
:(rackA-host01 through rackA-host10, and similarly for racks B, C, and E, skipping rackD)
Scans, LIDs, and slot, chip, and port numbers are always numeric, so ranges may be specified without the square brackets, as shown in the following example:
:switch03/1/1-4
:(ports 1 through 4 on slot 1 of chassis switch03)

A plural scan always describes a single object in a simple form (by not using any alternatives or images), as shown in the following example:
:switch03

FACT uses the following plural arguments:
*''LIDs''
*''chassis''
*''chips''
*''hosts''
*''managed-nodes''
*''multicast-groups''
*''ports''
*''scans''
*''switches''

'''Note''': Because all keywords can be abbreviated to a unique prefix, plural keywords such as chips and ports can be abbreviated to chip and port for the most common case of referring to a single unit. They keyword chassis can be either singular or plural.

==Using Command Modes==
FACT has two modes of operation:
*Interactive command-line processor mode
*Single-use command mode that performs a single function

===Using Interactive Mode===
As a command-line program, FACT reads commands from its input, parses them, and writes their output to its output. The following sample output shows FACT interactive mode:

$ fact
Cisco FACT 1.0
Copyright 2008, Cisco Systems, Inc.
fact> '''scan fabric'''
fact> '''show versions'''
node version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
fact> exit
$

===Using Single-Command Mode===
In single-command mode, a single command is passed to FACT as the program command arguments. FACT then runs the command, prints the results, and exits.

The following sample output shows the FACT single-command mode:

$ fact scan fabric
$ fact show versions
name version
----------------------- -------------------------------------
switch01 TopspinOS 2.9.0 releng #147 10/25/...
switch02 TopspinOS 2.8.0 releng #154 07/11/...
$

As a variant of single-command mode, the first word of the command, usually the verb, can be joined to the FACT name with a hyphen. The following sample output shows the FACT single-command mode:

$ '''fact-scan fabric'''
$ '''fact-show versions'''

To use shell completion to see available commands, join the FACT name with a hyphen, and enter the tab key:

$ '''fact'''-<TAB>

==Command-line Interface==

FACT looks for several environmental variables and accepts several command-lie options.
This section describes the FACT command-line interface and shows hot to use it.

===Command-line Options===

[[Using the CLI#Command-line Options|Table 2]] lists and describes the command-line options.

'''Table 2: Command-line Options'''

{| border="1" cellpadding="10" cellspacing="0"
!Option
!Description
|-
|'''-c''' ''file''
'''--config-file'''=''file''
|Reads primary configuration from the specified file.
|-
|'''--color'''='''always'''
|If tracing, specifies thatthe transcript is colorized, showing FACT requests in one color and the switch responses in another.
|-
|'''--color'''='''auto'''
|If tracing, specifies that the transcript is colorized only if the FACT standard output is a terminal. This behavior is the default.
|-
|'''--config-option'''=
''option''
|Adds or overrides a configuration option.
|-
|'''--credentials-from'''=''file''
|Adds credential information from the file.
See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|'''--guid-name'''=''guid''=''name''
|Adds a GUID name definition.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]] section.
|-
|'''--guid-names-
from'''=''file''
|Adds GUID name definitions from the specified file.
See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|'''-h
--help'''
|Prints a message describing messages.
|-
|'''--help-commands'''
|Lists FACT commands.
|-
|'''--managed-nodes-'''=''type: pattern''
|Adds a set of managed-nodes to those about which FACT is aware.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].

|-
|'''--managed-nodes-from'''=''file''
|Adds managed-nodes from the file.
See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|'''-s
--sequential'''
|Initiates sequential scan sessions to one managed node at a time. This option is helpful with the '''--trace''' command because output displays slower and more predictably. By default, FACT connects up to 50 managed nodes at a time during scans and installations. If sequential is specified, then FACT connects to one managed node at a time.
|-
|'''--subnet-manager'''=''domain name'' or ''IP address''
|Specifies the InfiniBand Subnet Manager host that FACT should use.
|-
|'''--trace''' and '''--sequential'''
|Runs sequential sessions to managed nodes and prints the session transcript.
|-
|'''-t
--trace'''
|By default, if '''--trace''' is not specified, then FACT will print the transcript of each session when that session is closed. If '''--trace''' is specified, FACT will print the transcript of each session as it occurs.
|-
|'''-v
--version'''
|Prints FACT version information and exits.
|}

===Environment Variables===
FACT uses environment variables to control the FACT configuration. [[Using the CLI#Environment Variables|Table 3]] lists and describes the FACT environment variables.

'''Table 3: Environment Variables'''

{| border="1" cellpadding="10" cellspacing="0"
!Variable
!Description
|-
|FACT_CONF
|Name of master configturation file.
See [[About FACT Configuration Files#About Master Configuration Files|About Master Configuration Files]].
|-
|FACT_CREDENTIAL_FILES
|List of files that contain credentials, separated by colons, as shown in the following example:

:FACT_CREDENTIAL_FILES=/etc/fact/cred1:/etc/fact/cred2
:states that the files /etc/fact/cred1 and /etc/fact/cred2 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About Credentials Files]].
|-
|FACT_GUID_NAMES
|List of GUID name definitions, separated by semicolons. Each definition has the form “GUID=name,” as shown in the following example:
:FACT_GUID_NAMES="00:1b:0d:0b:00:00:ca:a6=switchA;00:1b:0d:0b:00:00:ca:aa=switchB"
:defines switchA as the name for 00:1b:0d:0b:00:00:ca:a6 and switchB as the name for 00:1b:0d:0b:00:00:ca:aa

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_GUID_NAME_FILES
|List of files containing GUID name definitions, separated by colons, as shown in the following example:
:FACT_GUID_NAME_FILES=/tmp/guidnames1:/tmp/guidnames2 states that the files /tmp/guidnames1 and /tmp/guidnames1 contain GUID name definitions

See [[About FACT Configuration Files#About Credentials Files|About GUID Name Definitions]].
|-
|FACT_MANAGED_NODES
|In-line list of managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODES="host=ibmg-r1-evil:SFSOS switch=209.165.200.225
:defines a host named ibmg-r1-evil and an SFS OS switch named 209.165.200.225

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|-
|FACT_MANAGED_NODE_FILES
|List of files containing managed node definitions, separated by colons, as shown in the following example:
:FACT_MANAGED_NODE_FILES=/tmp/nodefile1:/tmp/nodefile2
:states that the files /tmp/nodefile1 and /tmp/nodefile2 contain managed node definitions

See [[About FACT Configuration Files#About Managed Node Definitions Files|About Managed Node Definitions Files]].
|}

===Correcting Commands===

'''Note''': This feature will be functional at FCS.

The system response to command line-errors is different when you use the question mark (?) to obtain help for a command. In this case, the system repeats your input following the subsequent prompt for ease of editing, as shown in the following example:

fact> show interfce ?
^
% Error: Unrecognized command
fact> show interfce

===Editing the CLI===

Command-line editing lets you modify a command line command that you have just entered or a command line that you entered previously in the CLI session. The CLI supports a variety of ways to move about and edit the currently displayed command line. [[Using the CLI#Editing the CLI|Table 4]] lists and describes these options.

'''Table 4: Key Stroke Shortcuts'''

{| border="1" cellpadding="10" cellspacing="0"
!Key Strokes
!Description
|-
|'''Ctrl'''-'''A'''
|Moves the cursor to the beginning of the line.
|-
|'''Ctrl'''-'''B'''
|Moves the cursor to the left (backward) one character.
|-
|'''Ctrl'''-'''D'''
|Deletes the current character. Exits FACT if the current input line is empty.
|-
|'''Ctrl'''-'''E'''
|Moves the cursor to the end of the line.
|-
|'''Ctrl'''-'''F'''
|Moves the cursor to the right (forward) one character.
|-
|'''Ctrl'''-'''G'''
|Erases the current input line.
|-
|'''Ctrl'''-'''H'''
|Deletes the character to the left of the cursor, analogous to the Backspace key.
|-
|'''Ctrl'''-'''I'''
|Completes the current word, analogous to the Tab key.
|-
|'''Ctrl'''-'''J'''
|Accepts the current line.
|-
|'''Ctrl'''-'''K'''
|Deletes text from the cursor to the end of the line.
|-
|'''Ctrl'''-'''L'''
|Refreshes the input line.
|-
|'''Ctrl'''-'''M'''
|Accepts the current line, analogous to the Return key.
|-
|'''Ctrl'''-'''N'''
|Proceeds to the next line in the command history.
|-
|'''Ctrl'''-'''P'''
|Moves to the previous line in the command history.
|-
|'''Ctrl'''-'''T'''
|Transposes the current and previous characters.
|-
|'''Ctrl'''-'''U'''
|Deletes all text to the left of the cursor, back to the beginning of the line.
|-
|'''Ctrl'''-'''W'''
|Deletes the word to the left of the cursor.
|-
|'''Ctrl'''-'''Z'''
|Suspends the FACT.
|-
|'''Ctrl'''-'''?'''
|Deletes the chatacter to the left of the cursor, analogous to the Delete key.
|-
|'''?'''
|Completes the current word.
|-
|'''Esc'''-'''[A'''
|Moves to the previous line in the command history.
|-
|'''Esc'''-'''[B'''
|Proceeds to the next line in the command history.
|-
|'''Esc'''-'''[C'''
|Moves the cursor to the right (forward) one character.
|-
|'''Esc'''-'''[D'''
|Moves the cursor to the left (backward) on character.
|-
|'''Esc'''-'''B'''
|Moves the cursor to the left (backward) one word.
|-
|'''Esc'''-'''C'''
|Converts characters, from the cursor to the end of the word, to uppercase.
|-
|'''Esc'''-'''D'''
|Deletes characters from the cursor through the end of the word.
|-
|'''Esc'''-'''F'''
|Moves the cursor right (forward) one word.
|-
|'''Esc'''-'''L'''
|Converts characters, from the cursor to the end of the word, to lowercase.
|-
|'''Esc'''-'''U'''
|Converts characters, from the cursor to the end of the word, to uppercase.
|-
|'''Esc'''-'''Ctrl'''-'''H'''
|Deletes the word to the left of the cursor.
|-
|'''Esc'''-'''Delete'''
|Deletes the character to the left of the cursor.
|-
|'''Down Arrow'''
|Proceeds to the next line in the command history.
|-
|'''Up Arrow'''
|Moves to the previous line in the command history.
|-
|'''Left Arrow'''
|Moves the cursor to the left (backward) one character.
|-
|'''Right Arrow'''
|Moves the cursor to the right (forward) one character.
|}

[[Category:Command Line Interface]]