nwmgr_btlan(1M)

NAME

nwmgr_btlan: nwmgr — network interface management command for btlan driver

SYNOPSIS

nwmgr

nwmgr [-g] [-v] [-c lan_instance | -S btlan ]

nwmgr [-g] --st [all | extmib | mib] -c lan_instance

nwmgr [-g] -A {all | attr1, attr2, ...} -c lan_instance

nwmgr [-g] -q info -c lan_instance

nwmgr -s -A attr1=value1, attr2=value2,... -c lan_instance

nwmgr -s -A all --sa --fr cu[rrent] -c lan_instance

nwmgr -s -A {all | attr1, attr2,...} [--cu] --fr de[fault] -c lan_instance

nwmgr -r -c lan_instance

nwmgr -r --st -c lan_instance

nwmgr --diag -A dest=mac_addr [--it number] [-A pktsize=bytes] [-A timeout=seconds] -c lan_instance

nwmgr -h [-g | -s | -r | --diag] [-c lan_instance | -S btlan]

Remarks

The lanadmin, lanscan, and linkloop commands are deprecated. These commands will be removed in a future HP-UX release. HP recommends the use of the replacement command nwmgr(1M) to perform all network interface-related tasks.

DESCRIPTION

The nwmgr program is a unified command to administer all Local Area Network (LAN) and RDMA interfaces of HP-UX. See nwmgr(1M) for general information about the command. This manpage describes nwmgr when working with the btlan driver.

The btlan driver is one of the HP-UX drivers that manages the 100BT Ethernet interfaces, both copper (100Base-T) and fiber (100Base-FX). Each interface has several attributes. Some attributes (for example, MTU) are configurable while others are read-only. In general, each attribute can have certain value during run time (which is its current value), another value in the configuration file that stores data across boots (its saved value), and an HP-supplied value that is applied by the driver after boot (its default value) but before the saved value is applied. See the Attributes section for a list of attributes.

For btlan interfaces, use the nwmgr command to display information (with the -g option, which is the default), to modify the settings (the -s option), to reset the interface or its statistics (the -r option), and to diagnose link connectivity (the --diag option).

Operations other than get, require the hpux.network.config authorization. For more information about authorizations and Role-Based Access Control, see rbac(5).

The output in each case can be obtained in either human-readable form (the default form) or in a script-friendly parseable form (with the --sc or --script option). The format for script-friendly output is described in the nwmgr(1M) manpage.

It is guaranteed that any change in the scriptable output across releases will contain only additions, but not modifications or deletions. The human-readable form can change across releases, including modifications and deletions, though the changes can be expected to be incremental.

The usage is explained in greater detail in the following section. The output format that is described is the human-readable one; references to the scriptable output are made as necessary.

Operations

The nwmgr command provides the following operations for the btlan interface.

--cra: Operation to perform Critical Resource Analysis on the interface.
--diag | --diagnose: Operation to diagnose/test link connectivity.
-g | --get: Operation to get/display interface settings.
-h | --help: Operation to display help information.
-r | --reset: Operation to reset interface or statistics. -s | --set Operation to set the attributes of the interface.

Options

The nwmgr command provides the following options for the btlan interface.

For more information about these options, refer to nwmgr(1M).

-A | --attribute

Operation to assign attributes for the operation.

Attributes that can be used for btlan interfaces are described in the Attributes section below.

-C | --class

Limits the scope of the operation to the classes provided.

-c | --class_instance

Specifies the target interface on which the operation is to be performed.

--fr | --from

Specifies the configuration from which the operation will copy data. The from option takes current or saved as argument.

-it | --iteration

Specifies how many test frame to send during a diagnose operation. The default is 1.

-q | --subsystem_qualifier

Specifies a keyword or special identifier used by a subsystem to add additional context for the operation being performed.

The argument supported for btlan is info, which provides more information on the instance of the btlan subsystem; such as, the hardware path, feature capabilities, current feature settings, the assigned NMID, speed, and MTU of the card.

-S | --subsystem

Specifies the target subsystem for the operation. For btlan subsystem, the option argument will always be btlan.

--sa | --saved

Specifies that the operation has to be performed on the saved configuration (persistent store).

-sc | --script

Display the output in script parseable format.

--st | --stats

Specifies that the operation applies to the statistics of the target.

-v | --verbose

Option to display more details in the output.

Attributes

The valid attributes for the btlan interface are:.

dest=mac_addr

Ethernet MAC address of the remote interface. Used with the --diagnose operation.

mac

Ethernet MAC Address. The default value is the factory MAC address.

mtu

Displays the maximum Ethernet payload size (MTU), in bytes. MTU above 1500 is not allowed.

Minimum value: 257.

Maximum value: 1500.

Default value: 1500.

pktsize=bytes

Specifies the package size of each test frame (for the diagnose operation). The default is 100 bytes.

speed

The actual values of Speed, Duplex and Autonegotiation of the Ethernet link if the link is up; otherwise, the configured values. Note that, for 100Base-FX, the speed is always fixed at 100 Mbps and the duplex can be set to either Half or Full Duplex.

The valid values allowed for speed in the command line for 100Base-FX are: 100FD and 100HD (case insensitive).

For 100Base-T, it is essential that the link partner has the same speed, duplex and auto-negotiation settings as the NIC being configured. The speed can be forced to 10 or 100 Mbps, with Full or Half Duplex, with auto-negotiation off. This is done by setting speed to one of 10HD, 10FD, 100HD, or 100FD (case insensitive). The valid values allowed for speed in the command line for 100Base-T are: 10HD, 10FD, 100HD, 100FD, and auto_on.

The valid values to set for speed for the 100Base-FX are 100FD and 100HD. Note that 10 Mbps and auto-negotiation are not supported speed configurations for the PCI 100Base-FX card.

The output for the speed attribute can take one of the two formats. In the human-readable format, it is of the form:

speed {Full | Half} Duplex (Autonegotiation : {On | Off})

Example:

100 Mbps Full Duplex (Autonegotiation : On).

In the script-friendly output, the speed value is of the form:

speed {FD | HD} auto_{on|of}

Examples:

100FD auto_on

100HD auto_off

Note that in both formats, the speed and duplex attributes are optional. They may not be present in some situations.

In the configuration file, there is an additional twist because there are separate variables for speed-duplex and auto-negotiation. For 100Base-T, the HP_BTLAN_SPEED variable can contain one of the following values 10HD, 10FD, 100HD, 100FD, and auto_on (same as the command line values). The HP_BTLAN_AUTONEG variable is of no relevance when HP_BTLAN_SPEED is set. For PCI 100Base-FX, the HP_BTLAN_AUTONEG variable is irrelevant.

timeout=seconds

Specifies how many seconds to wait for acknowledgement of each test frame (for the diagnose operation). The default is 5 seconds.

USAGE

Display Network Interfaces

The most basic command to display network interface information.

nwmgr

The command without any argument displays all the network interfaces in the system, including physical LAN interfaces (NICs), virtual LAN interfaces (VLANs and APA aggregates and failover groups), and RDMA interfaces.

View Basic Properties of Interfaces

The following command can be used to view the basic properties of one or more interfaces.

nwmgr [-g] [-v] [-c lan_instance | -S btlan]

nwmgr [--get] [--verbose] [--class_instance lan_instance | --subsystem btlan]

Note that the get operation is the default, so the -g option need not be specified explicitly.
If an interface is specified as a target with the -c option, only that interface gets displayed. If the -S option is specified, all btlan interfaces are displayed. The properties displayed for each interface are explained in nwmgr(1M).
The command without the verbose option displays a table, with one row for each interface that gets listed.
The verbose option (--verbose) changes the output to include more details about each interface displayed, and also changes the format to be line-oriented, with each line describing one property. The following attributes are displayed: mac, mtu, and speed.
More details on these attributes can be found in the Attributes section.

View Interface Statistics

The following command can be used to display interface statistics.

nwmgr [-g] --st [all | extmib | mib] -c lan_instance

nwmgr [--get] --stats [all | extmib | mib] --class_instance lan_instance

The arguments all, extmib, and mib are the only valid arguments for --stats for btlan drivers. all is the default if no argument is provided with --stats. It displays the same information as extmib which displays extended MIB statistics. mib displays a subset of MIB statistics of the interface.

View Interface Attributes

The following command can be used to display the current value of either all the attributes of the btlan interface (when the all keyword is specified), or the specified attributes (when they are listed by name, separated by commas).

nwmgr [-g] -A {all | attr1, attr2, ...} -c lan_instance

nwmgr [--get] --attribute {all | attr_list} --class_instance lan_instance

Each attribute is displayed on a separate line as a name-value pair.

View Interface Details

The following command can be used to display detail information of the interface.

nwmgr [-g] -q info -c lan_instance

nwmgr [--get] --qualifier info --class_instance lan_instance

This form displays interface-specific properties that are informational, often not configurable and subject to variation across drivers. In the case of btlan, the output is same as what is shown by: nwmgr -g -v -c lan_instance

Set Attribute Values

The following command can be used to set values to the specified attributes.

nwmgr -s -A attr1=value1, attr2=value2, ... -c lan_instance

nwmgr --set --attribute attr1=value1, attr2=value2,... --class_instance lan_instance

The attributes that can be set are: mtu, mac, and speed.

Save Current Attributes Values

The following command can be used to save the current value of each interface in the configuration file.

nwmgr -s -A all --sa --fr cu[rrent] -c lan_instance

nwmgr --set --attribute all --saved --from cu[rrent] --class_instance lan_instance

This form 'freezes' the current state of an interface; that is, it stores the current value of each attribute of an interface in the configuration file (/etc/rc.config.d/hpbtlanconf), so that the interface configuration is saved across boots. The user can also manually run the start-up script later to apply the configuration file values to the currently running kernel, by executing: /sbin/rc2.d/S333hpbtlan start.
This feature allows a user to experiment with the current values, and save the desired configuration.

Set Attribute Values from Default Values

The following command can be used to set default values to all attributes (if all is specified), or to selected attributes (if the attribute names are listed).

nwmgr -s -A {all | attr1, attr2, ...} [--cu] --fr de[fault] -c lan_instance

nwmgr --set --attribute {all | attr1, attr2, ...} [--current] --from de[fault] --class_instance lan_instance

This can be useful in rolling all the changes made to an interface since the time the system booted.

Reset an Interface

The following command can be used to reset an interface.

nwmgr -r -c lan_instance

nwmgr --reset --class_instance lan_instance

The interface is subjected to a PCI reset, which clears all previous state, including the interface statistics. The interface is then re-programmed with the attribute values that were current before the reset. Promiscuous mode and multicast addresses are preserved across the reset.
While the reset is in progress, the data traffic through the interface is interrupted. So, the command automatically performs a Critical Resource Analysis to see if the interface is data-critical; that is, any other resource depends for its functionality on the availability of the interface. If so, the reset is not performed. The reset can be forced, even if the interface is data-critical, by using the --force option.
It is possible for an interface to be system-critical; that is, the health of the system depends on the availability of the interface. In that case, the reset will not be performed even if the --force option is specified.

Reset Statistics of an Interface

The following command can be used to reset statistics of an interface.

nwmgr -r --st -c lan_instance

nwmgr --reset --stats --class_instance lan_instance

The data traffic statistics for an interface are cleared to zero. This includes the byte count and packet count for inbound and outbound traffic. Other aspects of the interface are left unmodified.

Diagnose Link Connectivity

The following command can be used to diagnose link connectivity.

nwmgr --diag [link] -A dest=mac_addr [--it number] [-A pktsize=bytes] [-A timeout=seconds] -c lan_instance

nwmgr --diagnose [link] --attribute dest=mac_addr [--iterations number] [--attribute pktsize=bytes] [--attribute timeout=seconds] --class_instance lan_instance

Link connectivity at the data link layer is checked by sending IEEE XID test frames to the specified destination MAC address and counting the replies.
The --iterations option specifies how many test frames to send. The default value is 1.
The pktsize attribute specifies the size of each test frame. The default value is 100 bytes.
The timeout attribute specifies how many seconds to wait for the acknowledgement of each test frame. The default value is 5 seconds.

RETURN VALUES

0: On success
<>0: On failure, the command returns values described in ERRORS below.

ERRORS

Below are the errors generated by nwmgr on failure.

EACCES: Attempt to set a read-only attribute.
EBUSY: The interface is currently inaccessible. This is usually because the interface is part of an APA aggregate, which prevents setting attributes on the interface.
EINVAL: One or more of the attributes or options is invalid for the operation.
ENOMEM: Memory allocation failed. This could be a transient condition.
ENOTSUP: Operation or feature is not supported.
ENXIO: The target interface could not be accessed.
EPERM: The user lacks the authorization hpux.network.config, which is required for this operation.
ERANGE: The specified values of one or more attributes is less than the minimum or more than the maximum.

EXAMPLES

List all LAN interfaces in the system.

nwmgr -C lan 

Display the speed and MTU of the btlan interface lan1.

nwmgr -A speed,mtu -c lan1 

Display all attributes of the btlan interface lan1.

nwmgr -A all -c lan1 

Set MTU to 1400 and speed to auto-negotiation on lan1.

nwmgr -s -A mtu=1400,speed=auto_on -c lan1 

Restore MTU and the MAC address to their defaults on lan1.

nwmgr --set -A mtu,mac --from de -c lan1

COMPARISON WITH LANADMIN COMMAND

Commands To Display Generic NIC Attributes

lanadmin	nwmgr
`lanadmin -m PPA`	`nwmgr [-g] -A mtu -c lan PPA`
`lanadmin -a PPA`	`nwmgr [-g] -A mac -c lan PPA`
`landamin -s PPA`	`nwmgr [-g] -A speed -c lan PPA`
`lanadmin -m -a -s PPA`	`nwmgr [-g] -A mtu,mac,speed -c lan PPA`
	`nwmgr [-g] -A all -c lan PPA`

Commands To Get NIC Statistics

lanadmin	nwmgr
`lanadmin -g PPA`	`nwmgr -g --st mib -c lan PPA`
`lanadmin -x stats drv PPA`	`nwmgr -g --st subsys -c lan PPA`
	`nwmgr -g -st mib,subsys -c lan PPA`
`lanadmin -g mibstats_ext PPA`	`nwmgr -g --st extmib -c lan PPA`

Commands To Set Generic NIC Attributes

lanadmin	nwmgr
lanadmin -M `mtu_size PPA`	nwmgr -s -A mtu=`mtu_size`
	-c lan`PPA`
lanadmin -A `MAC_Add PPA`	nwmgr -s -A mac=`MAC_Address`
	-c lan `PPA`
lanadmin -S `speed PPA`	N/A. NOTE: Speed can be specified
	as a combination of speed and
	duplexity only. For example:
	For example 1000FD, 100HD etc
landmin -X `speed_value PPA`	nwmgr -s -A speed=`speed_value`
	-c lan `PPA`

Command To Reset Statistics of a NIC

lanadmin	nwmgr
`lanadmin -c PPA`	`nwmgr -r -st -c lan PPA`

Command To Reset MTU To the Default Value

lanadmin	nwmgr
`lanadmin -R PPA`	`nwmgr -s -A mtu`
	`-from default -c lan PPA`

Command To Set To Default Configurations

lanadmin	nwmgr
`lanadmin -A DEFAULT PPA`	`nwmgr -s -A mac`
	`-from default -c lan PPA`
	`NOTE: Similarly default configuration`
	`can be set for the other attributes`
	`like speed,mtu, mac etc.`

Note:: The nwmgr equivalent for displaying the usage information is not available.
Note:: The lanadmin options that support apa and vlan are covered in the nwmgr_apa(1M) and nwmgr_vlan(1M) manpages.

COMPARISON WITH LINKLOOP COMMAND

Command to Test the Link Level Connectivity

linkloop	nwmgr
`linkloop -i PPA`	`nwmgr -diag -A dest=MAC_Address`
`MAC_Address`	`-c lanPPA`
`linkloop -i PPA`	`nwmgr --diag -A dest=linkaddr,`
`-n count -s size`	`pktsize=size, timeout=timeout`
`-t timeout MAC_Address`	`--it count -c lanPPA`
`linkloop -r rif`	`N/A`

Note:: nwmgr does not allow multiple station addresses to be specified in the same command line.

COMPARISON WITH LANSCAN COMMAND

Command To List Interfaces and Their Attributes

lanscan	nwmgr
`lanscan`	`nwmgr -g -v -c lan PPA`
	`nwmgr -C lan`
	`nwmgr -S gelan`

Command To Display Interface Names Only

lanscan	nwmgr
`lanscan -i`	`nwmgr -g -v -c lan PPA`
	`nwmgr -C lan -sc \| awk -F# '/if_state/ {print $1}'`

Command To Display MAC Types Only

lanscan	nwmgr
`lanscan -m`	`nwmgr -g -v -c lan PPA`
	`NOTE: nwmgr reports only on`
	`Ethernet links`

Command To Display NMIDs Only

lanscan	nwmgr
`lanscan -n`	`nwmgr -g -v -c lan PPA`

Command To Display the PPAs Only

lanscan	nwmgr
`lanscan -p`	`nwmgr -g -v -c lan PPA`
	`nwmgr -C lan --sc \| awk`
	`-F# '/if_state/ {print substr($1,4)}'`

Command To Display All Mac Addresses

lanscan	nwmgr
`lanscan -a`	`nwmgr -g -v -c lan PPA`

Note:: nwmgr displays the NIC attributes such as interface name, MAC type, the NMID, the PPA and the MAC address for only one NIC as only one instance of lan class instance can be specified for the --class_instance (-c) option.
Note:: The lanscan options (-l and -q) that support apa are covered in the nwmgr_apa(1M) manpage.

AUTHOR

nwmgr was developed by HP.

FILES

/etc/rc.config.d/hpbtlanconf: Contains the saved (persistent) configuration for btlan interfaces.
/sbin/rc2.d/S333hpbtlan: Startup script for the btlan driver, which applies the configured values to the kernel during run time. It is executed automatically after each reboot, and the user can also execute it by providing the argument start.