# Intel® Linux* LAN Adapters PROCfg Application

Overview

Prerequisites

Supported Features

Installation

Running the PROCfg Client

Known Issues

Support

## Overview

PROCfg is a reporting and configuration tool for Intel® PRO LAN adapters (10/100 and 1000) and Intel Advanced Networking Services (iANS). It works with the Intel e100, e1000, and iANS drivers on Intel 32-bit architectures running Linux*.

The tool consists of three parts: the daemon procfgd, the procfg command-line client tool, and the installer. At this time only local use is supported.

## Prerequisites

procfgd requires the following minimal versions:

- Linux kernels 2.2.x through 2.2.20 or 2.4.x through 2.4.7

- Any combination of the following Intel drivers:

  > e100 version 1.8.x
  > e1000 version 4.0.x
  > iANS version 1.6.x

  | NOTE: The non-Intel driver eepro100 must not be loaded.

- openssl* 0.9.6 or higher security package installed on the system.

  | NOTE: openssl is installed with Red Hat* Linux 7.0 and above. If the package is already installed, make sure the libcrypto.so.1 file is in /usr/lib. If not, see the instructions below for creating libcrypto.so.1.

  If you do not have openssl installed, download the package from http://www.openssl.org and configure openssl with 'config shared' to create the libcrypto.so.0.9.x shared library.

  To create libcrypto.so.1 under /usr/lib, you must copy libcrypto.so.0.9.x to /usr/lib and create a link named libcrypto.so.1 to libcrypto.so.0.9.x:

  > cp libcrypto.so.0.9.x /usr/lib
  > cd /usr/lib
  > ln -s libcrypto.so.0.9.x libcrypto.so.1

## Supported Features

procfg includes the following features for Intel adapters:

Viewing:

- Bus, Slot, and IRQ numbers for physical adapters

- Static driver info: name, version, path, date, size (base and iANS)

- Adapter load-time parameters and their values (e100 only)

- Dynamic information: link state, speed and duplex (Intel adapters only), and statistical counters

- Information for configuring iANS: teaming/VLAN support, adapter capability

- Interface information on loaded adapters and teams including:

  - Virtual interfaces (VLANs)

  - Aliases

- The iANS topology (teams, member, VLANs)

- Team and member parameter values

- Dynamic information regarding the state of a team and the state of its members

Setting:

- MAC, inet, mask, and broadcast addresses

- MTU size

- Interface state

- Load-time parameters (e100 only -- when none of the PRO/100 adapters are members of an iANS team or have VLANs)

- Team settings: initial config, add members, change teaming mode, change probes settings

- VLAN settings: add/delete VLANs for a physical adapter or team (adapters controlled by e100 or e1000 drivers only)

  | NOTE: Once a physical adapter is a team member or has VLANs, any operation issued by ifconfig on the individual network interfaces of such an adapter may cause corruption. As a precaution, Intel recommends using procfg to configure the interfaces and ifconfig only for operations that procfg does not support.

Special Functions:

- Blink hardware LEDs to identify a specific adapter (e100 only)

- Error messages:

  - User initiated operation failures

  - Daemon initiated operation failures, usually polling failure

  | NOTE: All error messages are printed to the console.

Logging:

- Configuration changes

- If found during periodic polling noted as "external events"

- If user change noted as "events generated by session ID X"

- Errors that occur only in the daemon

  | NOTE: Events are logged in /var/log/procfgd.log.

The PROCfg application does not:

- Load or unload base drivers

- Save or restore configurations (including ongoing boots)

## Installation

1. Copy the files to a directory of your choice. The following files should be placed in the same directory:

   > procfg.tar.gz
   > procfgd.tar.gz
   > procfg_install.tar.gz

2. Enter:

   > tar xzvf procfg_install.tar.gz

   The following files should appear:

   > INSTALL
   > ADDUSER
   > procfg.1
   > README
   > ldistrib.txt

3. Enter:

   > ./INSTALL

   The INSTALL script opens the tar files and copies the following files to the indicated location:

   > procfgd (the server application) - to /usr/sbin
   > procfg (the client application) - to /usr/sbin
   > procfg.1 (the man page for the client application) - to the default man directory

   The ADDUSER script remains in the current directory.

4. To run the PROCfg server, first logon to the system as root. Then, enter:

   > procfgd

   | NOTE: To change the configuration for the PRO LAN adapters, including ANS, procfgd requires a non-default username and password. To configure a user, see the instructions in #5 below.

   The daemon runs by default on port 8086. If this port is taken or procfgd is already running on the default port, the following error message is printed on the screen:

   > init_master_agent: Invalid local port (Address already in use) Server Exiting with code 1

   In order to run the server on an alternate port, use the -p option:

   > procfgd -p <port number>

5. To add a new read/write-access user to the PROCfg server, first logon as root. Make sure procfgd is not running. Enter the following, where the password is at least 8 characters long:

   > ADDUSER <username> <password>

   Multiple read/write users may be added. The new username(s)/password(s) are added to the /var/.procfgd/procfgd.conf file. After running the server once, this file is encrypted, but the password is visible while typing it.

   To configure a user in the PROCfg client (procfg), see the Switches section below.

   | NOTE: A single read-only user is configured by default on the PROCfg server. To simply view settings no username or password are required, as long as the default username and password (username=procfgd, password=pRoCfGdPaSs) have been left in place.

## Running the PROCfg Client

The following parameters are used by entering them on the command line with the procfg command. When issuing a command, the following syntax must be used:

> procfg [<switch(es)>] <command> [<object(s)>] [<option(s)>]

Object(s) can be an interface name (ethx), team name, or list of interfaces or team names (eth0 eth1 ...).

Each switch has a long name as well. See the man page for a more detailed description of the command options.

| WARNING: The procfgd daemon must be running before issuing a command.

### Switches

Switch | Description
--- | ---
-p <port> | If the procfgd daemon is not using the default port, you must set the procfg application to the same port. If a port number is not specified, the default port (8086) is used.
-U <username> -P <password> | Set the username and password to access the server application. The username and password must be pre-configured in the server (see the Installation section). If you do not specify a username or password, the defaults are used (username: procfgd, password: pRoCfGdPaSs).
| NOTE: The default username is authorized for 'get' operations only.
-t <num_seconds> | This parameter specifies how long, in seconds, the procfg application waits for response from procfgd. The default is 4 seconds and should only be increased for a highly stressed server.

To allow a non-default User to write without having to input the username and password on each command, or to save changes to any of these values create a configuration file named procfg.conf. Place it in your home directory under a procfg directory (~/.procfg/procfg.conf). This file may contain the new username, password, port or timeout. The new settings are retained across reboots. An example of the procfg.conf file:

> username anyone
> password anyonepassword
> port 1012
> timeout 20

### Commands - Informational

Command | Description
--- | ---
help or -h [<command_in-question> [-a]] | Displays command usage. Use -a for advanced information.
adapters [<ethx(s) or lspci_adapter_name(s)>] [-a -v -i -h -p[d]] | Displays general information on named adapters in the system including: unique name, system name, link state, speed, duplex, team membership, vendor (I - for Intel, NI - for non-Intel), VLANs, interfaces, hardware info, adapter load time parameters.
| NOTE: Link state, speed, and duplex are not supplied for non-Intel adapters. Non-Intel drivers are shown only if iANS is loaded. For specific switches see the man page.
blink ethx [-t <num_seconds>] | Identifies adapter by blinking hardware LED. Default blink time is 10 seconds.
| NOTE: ethx must be an adapter controlled by the e100 driver. This parameter is currently not available for PRO/1000 adapters.
interfaces [<ethx(s)>] [-a -d -s -x] | Displays general information on all interfaces in the system including: interface name, inet address, broadcast address, netmask, VLAN ID, MTU size, driver info, and statistics.
teams [<team_name(s)>] [-m -p -v -i] | Displays information on the teams in the system including: teaming mode, team current primary, team state, team link state, team speed, team members table, team VLANs table, team hwaddr, and team probe parameters. Teams probe parameters are: addressing mode, check time out, send time, max retry count, receive time out, receive back cycles, probe burst size. Team speed is defined differently for the different teaming modes. For AFT and ALB Team speed = primary speed. For FEC and GEC Team speed = sum of speeds of all members.
tree | Demonstrates the topology of the system. Gives a non-detailed listing of all stand-alone adapters and their VLANs, teams and their VLANs, and members.
vlans | Displays information on VLANs including: interface name,VLAN name and ID.

### Commands - Team/VLAN Configuration

Command | Description
--- | ---
addteam <team_name> eth0 eth1 ... [-M <mode>] [-e/-d] [-a <addrmode>] [-c <num>] [-s <num>] [-m <num>] [-t <num>] [-r <num>] [-b <num>] | Add team. <team_name> must be no longer than 8 characters, must start with a letter, and must NOT start with the letters "eth". The default teaming mode is AFT. For other default values, see the man page.
addmem <team_name> <ethx> [-p <priority>] <ethx> [-p <priority>] ... | Add adapter to team. Default priority is none.
addvlans <ethx>/<team_name> -i <VLAN_ID(s)> [-n <VLAN_name>] -i <VLAN_ID(s)> [-n <VLAN_name>] ... | Add VLANs to a team or a physical adapter. Each set of VLAN IDs can be tagged with a VLAN name. The VLAN ID range is 0 - 4095.
| NOTE: if a VLAN ID appears twice in the list an error occurs.
delmem <team_name> <member_name> | Delete adapter from team.
delteam <team_name> | Delete team.
delvlans <ethx>/<team_name> -i <VLAN_ID(s)> | Delete VLANs from a team or physical adapter. If a VLAN ID appears twice in the list an error occurs. delvlans will not remove VLANs if their interface is up.

### Commands - Setting Parameters

| NOTE: Enter 'procfg <command>' for a list of the objects that can be configured by the specfied command. Enter 'procfg <command> <object>' for a list of parameters that can be set by the specfied command and the current values of those parameters.

Command | Description
--- | ---
adpcfg [<ethx>] [-h <hwaddr>] | Sets adapter hw addr.
adpsetp [<ethx(s)>] [-p <parameter_name1> = <val1>] [-p <parameter_name2> = <val2>] ... | Sets load time parameters for adapters that are not in a team or VLAN and that are using the e100 driver. This operation downs any existing ethx that is using the e100 driver and unloads the driver. Then, the driver is reloaded with the new parameters, and the previous configuration is saved and restored.
| NOTE: This parameter is currently not available for PRO/1000 adapters.
ifcfg [<ethx(s)>] [-i <addr>] [-n <mask>] [-b <addr>] [-u <pktsize>] [-s <up/down>] | Sets interfaces (all in list set to same value).
| NOTE: Setting aliased interfaces to the same IP address should fail. "ifcfg ethx:i -i 0.0.0.0" removes the alias i from ethx. "ifcfg ethx:i -s down" also removes the alias.
memcfg <member_name> -p <priority> | Sets member priority.
teamcfg [<team_name>] [-h <addr>] -[<same_as_addteam_switches>] | Configures team.

## Known Issues

| NOTE: For Linux distribution-specific information, see ldistrib.htm.

1. After killing procfgd, trying to run it again fails and an error message is displayed about the port's address being in use.

   procfgd runs another daemon, called iansd, when iANS is loaded. When killing procfgd, iansd remains running, and it occupies the port that was used by procfgd. As a workaround, kill iansd before running procfgd.

2. "Unable to apply session" or "cache invalidated for session" appears on the screen or in the procfgd log.

   When running PROCfg commands in a script, some commands may fail because of timing issues (some commands take longer than script allows). As a workaround run the script again or insert pauses between the commands in the script.

3. An error message, "procfg: Unknown engine id, Unable to connect to host", is seen for every PROCfg command.

   Since PROCfg is a client-server application, the loopback interface in the system (lo) must be up, and it must contain an IP address. Configure the loopback interface up by entering:

   > ifconfig lo <IP_address>

4. Issuing the 'adpsetp' command on an interface with aliases causes the aliases to disappear.

5. An error message regarding a missing shared object (libpopt.so.0) may appear when running procfgd. This file is not installed by default on some Linux distributions. If such an error occurs, libpopt.so.0 may be downloaded from Linux resource websites. Install the file in /usr/lib.

## Support

For general information and support, go to the Intel support website at:

> http://support.intel.com

If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to linux.nics@intel.com.

Copyright © 2002 Intel Corporation. Legal Information