Intel(R) Linux* LAN Adapters PROCfg Application
===============================================

January 15, 2002


Contents
========
- Overview
- Prerequisites
- Supported Features
- Installation
- Running the PROCfg Client
- Known Issues
- License


Overview
========

PROCfg is a reporting and configuration tool for Intel(R) 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 
       - 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
       LICENSE.net-snmp.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
   --------

   -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
   ------------------------
        
   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.

       Example of the output of the tree command:
          - adapter eth0
                VLANs:
                  veth0_2    2
                  veth0_4    4
          -adapter eth1
                VLANs:
          -team t0
                VLANs:
                  vt0_5    5
                  vt0_8    8
                members:
                  eth2 
                  eth3  

   vlans
       Displays information on VLANs including: interface name,VLAN name and 
       ID. 


   Commands - Team/VLAN Configuration
   ----------------------------------

   addmem <team_name> <ethx> [-p <priority>] <ethx> [-p <priority>] ...
       Add adapter to team. Default priority is none.

   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.	

   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
   -----------------------------

   NOTES: 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.   


   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).

       NOTES: 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 the ldistrib.txt file
      included in the PROCfg tar file.

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" may appear 
   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", 
   may be 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.


* Other names and brands may be claimed as the property of others.


License
=======

Intel Networking Components Software License Agreement       

      IMPORTANT - READ BEFORE COPYING, INSTALLING OR USING.
      BY DOWNLOADING OR COPYING THIS SOFTWARE, YOU ("LICENSEE") ARE AGREEING TO 
      BE BOUND BY THE TERMS OF THIS AGREEMENT. DO NOT DOWNLOAD, INSTALL OR USE 
      THIS SOFTWARE UNTIL YOU HAVE CAREFULLY READ AND AGREED TO THE FOLLOWING 
      TERMS AND CONDITIONS. IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, 
      DO NOT DOWNLOAD, INSTALL OR USE THIS SOFTWARE.


INTEL CORPORATION ("Intel")
2111 N.E. 25th Avenue
Hillsboro, OR 97124

      1
      DEFINITIONS

      1.1
      "Object Code" means the executable or binary version of the Licensed 
      Program identified below, as provided to Licensee, and as modified by 
      Licensee for use with Licensee Product.

      1.2
      "Intel Product" means any Intel component or adapter card which Licensor 
      purchases from Intel.

      1.3
      "Licensed Program(s)" means the software program(s) in executable, or 
      Object Code as set forth in Exhibit A. 

      1.4
      "Licensee Product" shall mean any Licensee network interconnect products 
      which is integrated or packaged with an Intel product.

      2
      LICENSE GRANT AND RESTRICTIONS

      2.1
      Intel license grants are set forth in Exhibit A. Distribution rights for 
      the Licensed Program granted in Exhibit A, if any, are conditioned upon 
      Licensee's distribution and license to its end-user customers pursuant to 
      a written license agreement. Such license agreement may be a 
      "break-the-seal" license agreement. At a minimum such license shall be for 
      Object Code only and no less stringent than the terms of this license.

      2.2
      No rights or licenses are granted by Intel to Licensee, expressly or by 
      implication, with respect to any proprietary information or patent, 
      copyright, mask work, trademark, trade secret, or other intellectual 
      property right owned or controlled by Intel, except as expressly provided 
      in this Agreement

      3
      PROPRIETARY RIGHTS

      The Licensed Program and all copies are and shall remain the property of 
      Intel. If the applicable License Grant in Exhibit A provides for the 
      creation of modifications or provides for the creation of modifications or 
      derivative works, they shall be the property of Licensee subject to any 
      rights Intel may have in the Licensed Programs. Licensee understands and 
      agrees that except as expressly granted in Exhibit A, Licensee does not 
      have the right to distribute the Licensed Program as a stand-alone 
      product, nor to grant a license to any other parties to distribute the 
      Licensed Program under this Agreement. Intel retains all intellectual 
      property rights including, without limitation, the right to use, copy, 
      modify, sublicense, and distribute, the Licensed Program.

      4
      LIMITED WARRANTY

      INTEL MAKES NO WARRANTY OF ANY KIND WITH REGARD TO LICENSED PROGRAM. THE 
      LICENSED PROGRAM IS LICENSED "AS IS", AND INTEL IS NOT OBLIGATED TO 
      PROVIDE ANY SUPPORT OR ASSISTANCE UNDER THIS AGREEMENT. NO INSTALLATION, 
      TRAINING OR OTHER SERVICES WILL BE PROVIDED BY INTEL UNDER THIS AGREEMENT. 
      INTEL IS NOT OBLIGATED TO PROVIDE ANY UPDATES, ENHANCEMENTS OR EXTENSIONS, 
      ALTHOUGH INTEL MAY, AT ITS DISCRETION, PROVIDE UPDATES CREATED IN THE 
      NORMAL COURSE OF BUSINESS. ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND 
      FITNESS FOR A PARTICULAR PURPOSE AND ALL OTHER WARRANTIES, EXPRESS OR 
      IMPLIED ARE EXCLUDED, AND WILL NOT APPLY TO THE LICENSED PROGRAM IN ANY 
      FORM.

      Specifically, Intel will not have any liability to Licensee, or any third 
      party for:

      a) any defects in the Licensed Program furnished hereunder; or

      b) inability of Licensee to develop or modify the Licensed Program to 
      conform to any given performance level or specification; or 

      c) any claim of Licensee or any third party with respect to Licensed 
      Program arising out of the use or distribution of Licensed Program.

      INTEL DOES NOT MAKE ANY WARRANTIES OF ANY KIND THAT THE LICENSED PROGRAM 
      DOES NOT OR WILL NOT INFRINGE ANY COPYRIGHT, MASK WORK, PATENT, TRADE 
      SECRET, TRADEMARK, OR OTHER INTELLECTUAL PROPERTY RIGHT OF ANY THIRD 
      PARTY IN ANY COUNTRY. 

      5
      LIMITATION OF LIABILITY

      NEITHER INTEL NOR ITS VENDORS SHALL BE LIABLE FOR ANY INDIRECT, SPECIAL, 
      INCIDENTAL, SPECULATIVE, OR CONSEQUENTIAL DAMAGES OF ANY KIND, INCLUDING 
      BUT NOT LIMITED TO LOSS OF PROFITS, LOSS OF USE, LOSS OF GOODWILL, OR 
      INTERRUPTION OF BUSINESS, WHETHER UNDER THIS AGREEMENT OR OTHERWISE, EVEN 
      IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

      6
      INDEMNIFICATION

      Licensee shall indemnify Intel and hold Intel harmless from and against 
      any and all actions, claims, defenses, damages, expenses (including 
      attorneys' fees) and liabilities arising from Licensee's use, 
      modification, sublicensing or other disposition of the Licensed Program, 
      including suits or claims brought against Intel by any third parties for 
      Licensee's breach of any Licensee warranty to the third party or for 
      Licensee's negligence to the third party. Licensee's duties under this 
      Section 6 extend to any matters arising out of the alleged infringement by 
      the Licensed Program as modified by Licensee, of any copyright, mask work, 
      patent, trade secret, trademark, or other intellectual property right.

      7
      CONFIDENTIALITY

      Licensee agrees to receive and hold the Object Code in confidence for a 
      period of ten (10) years after receipt. Licensee agrees to exercise the 
      same degree of care in preventing the disclosure of such Object Code as 
      Licensee uses to protect its own proprietary information. As a minimum 
      protection, Licensee shall limit the disclosure of the Object Code to 
      employees having a need to know such information, and shall not disclose 
      the Object Code to any third party individual, corporation, independent 
      contractor, consultant or other entity without the prior written consent 
      of Intel. This obligation will not apply to any Object Code which is:

      a) published or otherwise available to the public other than by breach of 
      this License Agreement by Licensee or 

      b) rightfully received by Licensee from a third party without confidential 
      limitations; or

      c) independently developed by Licensee by employees having no access to 
      the Object Code; or

      d) known to Licensee prior to its first receipt of same from Intel; or

      e) hereinafter disclosed by Intel to a third party without restriction on 
      disclosure.

      8
      TERM AND TERMINATION

      8.1
      The term of this Agreement shall commence on the Effective Date, and shall 
      continue until Licensee ceases to utilize the Licensed Programs or this 
      Agreement is terminated pursuant to Sections 8.2 or 8.3. 

      8.2
      Licensee may terminate this Agreement and the licenses granted herein at 
      any time upon written notice to Intel.

      8.3
      Intel reserves the right to have audits conducted to verify compliance 
      with this Agreement. In the event that Intel, in its sole discretion, 
      determines that the Licensed Program is not being used by Licensee 
      exclusively for the purposes set forth above, or if Licensee is in breach 
      of any of the terms and conditions of this Agreement, Intel has the right 
      to immediately terminate this License Agreement. In such event, Licensee 
      agrees to immediately discontinue use and distribution of Object Code.

      8.4
      Upon termination of this Agreement for any reason, the sections of this 
      Agreement entitled Indemnification, Limitation of Liability, and 
      Confidentiality shall remain in effect.

      9
      U.S. GOVERNMENT RESTRICTED RIGHTS

      All copies of the Object Code distributed directly or indirectly to the 
      U.S. government are governed by and must be marked with the following 
      legend:

      "The enclosed software products and documentation were developed at 
      private expense, and are provided with "RESTRICTED RIGHTS." Use, 
      duplication or disclosure by the government is subject to restrictions as 
      set forth in FAR 52.227-14 and DFARS 252.227-7013 et. seq. or its 
      successor. The use of this product by the government constitutes 
      acknowledgment of Intel's proprietary rights in the product."

      10
      NOTICES

      Notice to Intel shall be addressed to 

      Intel Corporation 2111 N.E. 25th Avenue Hillsboro, OR 97124 Attn.: General 
      Counsel

      11
      EXPORT CONTROL

      Licensee agrees and certifies that the Licensed Program will not be 
      shipped either directly, or indirectly to country groups Q, S, W, Y, Z, 
      Afghanistan, The People's Republic of China, or Iraq without a validated 
      export license from the U.S. Department of Commerce.

      12
      RELATIONSHIP OF THE PARTIES

      Neither party hereto will be deemed the agent or legal representative of 
      the other for any purpose whatsoever and each party will act as an 
      independent contractor with regard to the other in its performance under 
      this Agreement. Nothing herein will authorize either party to create any 
      obligation or responsibility whatsoever, express or implied, on behalf of 
      the other or to bind the other in any manner, or to make any 
      representation, commitment or warranty on behalf of the other.

      13
      GENERAL

      13.1
      Any claim arising under or relating to this Agreement shall be governed by 
      the internal substantive laws of the State of Delaware or federal courts 
      located in Delaware without regard to principles of conflict of laws. Each 
      party hereby agrees to jurisdiction and venue in the courts of the State 
      of Delaware for all disputes and litigation arising under or relating to 
      this Agreement. This provision is meant to comply with 6 Del. C . Section 
      2708(a).

      13.2
      The rights and remedies provided in this Agreement are in addition to any 
      other rights and remedies provided at law or in equity.

      13.3
      This Agreement, including its attachments and Exhibits, constitutes the 
      entire agreement between the parties.

EXHIBIT A

"Licensed Program" shall include the following files from the Intel Linux LAN 
Adapters PROCfg Application release:

./procfg.tar.gz:
procfg

./procfgd.tar.gz:
procfgd

./procfg_install.tar.gz:
ADDUSER
INSTALL
ldistrib.txt
procfg.1
README


      LICENSE GRANT:
      OBJECT CODE REPRODUCTION AND DISTRIBUTION RIGHTS
      Intel grants to Licensee only, and not to any subsidiary, affiliate, or 
      independent contractor of Licensee, a non-exclusive, non-transferable, 
      royalty-free license under Intel copyrights to the Object Code to 
      reproduce and distribute the Object Code only as an integral part of or 
      incorporated in Licensee Product or as a standalone Object Code 
      maintenance update for existing end users of Licensee Products, excluding 
      any other standalone products. Licensee shall not reverse engineer, 
      decompile, or disassemble the Object Code portion of the Licensed Program.


This product contains copyrighted programs that are used with permission and 
are the property of the respective owners as described in the included file: 
"LICENSE.net-snmp.txt".

* Legal Information and Privacy Policy  2002 Intel Corporation