"Fossies" - the Fresh Open Source Software Archive

Member "open-fcoe-3.19/fcoe-utils/doc/fcoemon.txt" (15 Apr 2015, 9301 Bytes) of package /linux/misc/open-fcoe-3.19.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "fcoemon.txt": 3.11_vs_3.19.

    1 ///////////////////////////////////////////////////////////////////////////
    2 // vim:syntax=asciidoc:tw=75:
    3 //
    4 // This is an asciidoc text file, which will be converted into a UNIX man
    5 // page using asciidoc and the DocBook XSL stylesheets.
    6 //
    7 // If you are going to update this documentation, please modify this file
    8 // and then regenerate the nroff formatted man page using the Makefile.
    9 ///////////////////////////////////////////////////////////////////////////
   10 
   11 FCOEMON(8)
   12 ==========
   13 :man source: Open-FCoE
   14 :man manual: Open-FCoE Tools
   15 
   16 NAME
   17 ----
   18 fcoemon - Open-FCoE service daemon
   19 
   20 SYNOPSIS
   21 --------
   22 *fcoemon* [-f|--foreground] [-l|--legacy] [-d|--debug] [-s|--syslog]
   23 
   24 *fcoemon* -h|--help
   25 
   26 *fcoemon* -v|--version
   27 
   28 DESCRIPTION
   29 -----------
   30 The *fcoemon* daemon is the core component of the _Open-FCoE_ management
   31 service.
   32 
   33 The primary function of *fcoemon* is to control FCoE instances. *fcoemon*
   34 will create, destroy, reset, enable and disable FCoE instances based on
   35 system configuration, administrative commands, and runtime events.
   36 
   37 On startup, *fcoemon* will create FCoE instances defined by the
   38 configuration files (see _FILES_ section below). Since FCoE typically
   39 relies on the Data Center Bridging (DCB) capabilities of an Ethernet
   40 interface, *fcoemon* establishes a connection with the LLDP daemon *lldpad*
   41 to query the status of the DCB features on relevant Ethernet interfaces and
   42 receive DCB configuration change events.
   43 
   44 During runtime, *fcoemon* will monitor network and *lldpad* events for the
   45 relevant Ethernet interfaces and perform appropriate actions (create,
   46 destroy, enable, disable) on the FCoE instances. *fcoemon* also provides a
   47 client interface via which the *fcoeadm* utility is able to issue commands.
   48 
   49 Installation of the _fcoe-utils_ package will set up an _fcoe_ service which
   50 will control the execution of the *fcoemon* daemon.
   51 
   52 OPTIONS
   53 -------
   54 *-f*, *--foreground*::
   55 	Run *fcoemon* in the foreground.
   56 *-d*, *--debug*::
   57 	Enable debugging messages.
   58 *-l*, *--legacy*::
   59 	Force fcoemon to use the legacy /sys/module/libfcoe/parameters/
   60 	interface. The default is to use the newer /sys/bus/fcoe/ interfaces
   61 	if they are available.
   62 *-s*, *--syslog*::
   63 	Use syslogd for logging. The default behavior is to log to stdout
   64 	and stderr.
   65 *-h*, *--help*::
   66 	Show help message with basic usage instructions
   67 *-v*, *--version*::
   68 	Show the version of the *fcoemon* command.
   69 
   70 
   71 TERMINOLOGY
   72 -----------
   73 _DCB_::
   74 	Data Center Bridging A set of Ethernet enhancement standards
   75 	developed by the IEEE 802.1 Working Group.
   76  ::
   77 	See <http://www.ieee802.org/1/pages/dcbridges.html> for more
   78 	information.
   79 
   80 _DCBX_::
   81 	DCB Capabilities Exchange Protocol, implemented by the DCB module
   82 	of *lldpad*. DCBX exchanges DCB capabilities and configuration with
   83 	a link partner as a series of values transferred using the Link Layer
   84 	Discovery Protocol (LLDP).
   85 
   86 _PFC_::
   87 	Priority-based Flow Control, a _DCB_ feature.
   88 
   89 _App:FCoE_::
   90 	The FCoE instance of application specific parameters in DCBX.
   91 
   92 CRITERIA USED FOR CONTROLLING THE FCOE INSTANCE
   93 -----------------------------------------------
   94 *fcoemon* uses two information sources for determining when to create an
   95 FCoE instance: the state of the network interface, which may be a VLAN
   96 interface, and, if required for the FCoE instance, the state of the DCB
   97 configuration on the physical Ethernet interface.
   98 
   99 First of all, the network interface must be "up" for the FCoE instance to
  100 be created. Secondly, if the FCoE configuration indicates that DCB is
  101 required, then the following criteria must be satisfied before the FCoE
  102 interface is created:
  103 
  104 * DCB is enabled on the Ethernet interface.
  105 * The PFC DCB feature is enabled and operational.
  106 * The App:FCoE DCB feature is enabled and operational.
  107 * The priority indicated by the App:FCoE feature is also enabled for PFC.
  108 
  109 Once the FCoE instance is created by *fcoemon*, it will only be destroyed
  110 under the following conditions:
  111 
  112 * The driver for the Ethernet interface is unloaded.
  113 * A user administratively destroys the FCoE instance using *fcoeadm*.
  114 * The *fcoemon* daemon is terminated.
  115 
  116 If DCB is required for the FCoE instance, and the DCB settings change after
  117 the interface is created, the following criteria are used to disable the
  118 FCoE instance:
  119 
  120 * DCB is disabled on the Ethernet interface.
  121 * The App:FCoE DCB feature is not enabled.
  122 * The App:FCoE and PFC features are operational AND the priority indicated
  123   by App:FCoE is not enabled for PFC.
  124 
  125 Otherwise, the FCoE instance will always remain enabled.
  126 
  127 CONFIGURATION
  128 -------------
  129 Once the _fcoe-utils_ and *lldpad* packages have been installed and the
  130 corresponding services are running, there are a few simple configuration
  131 steps required to get an FCoE instance up and running. The following
  132 assumes that DCB will be required for the interface.
  133 
  134 * Ensure that the configuration on the peer device (e.g. FCoE capable
  135   switch) has the necessary configurations (VLANs, DCB, DCBX).
  136 * Configure any needed VLAN interfaces on the local system.
  137 * Create and configure _/etc/fcoe/cfg-<ifname>_ files for the network
  138   interfaces over which FCoE instances need to be created. See the _FILES_
  139   sections for details. Note that _ifname_ may be for a VLAN interface.
  140 * Restart the *fcoe* service (i.e. *fcoemon*).
  141 * The default DCB configuration of an Ethernet interface managed by
  142   *lldpad* requires the following configuration using *dcbtool*.
  143 
  144 	dcbtool sc ethX dcb on		<-- enable DCB on the interface
  145 	dcbtool sc ethX app:fcoe e:1	<-- enable App:FCoE on the interface
  146 
  147 These steps only need to be done one time. Note that if other DCB
  148 configuration changes have been made with *dcbtool*, then additional
  149 changes may need to be made in order to satisfy the DCB criteria for
  150 creating an FCoE instance. Consult *dcbtool* for details.
  151 
  152 Once these configuration steps have been performed, use *fcoeadm* to query
  153 the status of the FCoE instances.
  154 
  155 FILES
  156 -----
  157 /etc/fcoe/config
  158 ~~~~~~~~~~~~~~~~
  159 This is the primary configuration file for the *fcoe* system service. The
  160 default options in this file are: *DEBUG="no"* and *USE_SYSLOG="yes"*. The
  161 former is used to enable debugging messages from the fcoe service script
  162 and *fcoemon* (via the *--debug* option). The latter is to indicate if the
  163 log messages are to be output to the system log (via the *--syslog*
  164 option). *SUPPORTED_DRIVERS* is the list of drivers to automatically load
  165 during fcoe service start. Any changes to this file will require a restart
  166 of the *fcoe* service.
  167 
  168 /etc/fcoe/cfg-<ifname>
  169 ~~~~~~~~~~~~~~~~~~~~~~
  170 These files are read by *fcoemon* on initialization. They are used to
  171 indicate which Ethernet or VLAN interfaces should have FCoE instances
  172 created. The option values in this file normally are: *FCOE_ENABLE="yes"*,
  173 *DCB_REQUIRED="yes"*, and *AUTO_VLAN="yes"*, though if the variable
  174 values are omitted, they default to "no".
  175 
  176 _FCOE_ENABLE_::
  177 	is used to enable/disable creation of the FCoE instance.  If
  178 	FCoE_ENABLE is set to "no", then the other configuration values
  179 	have no effect.
  180 
  181 _DCB_REQUIRED_::
  182 	indicates if the DCB service is required on the Ethernet interface.
  183 
  184 _AUTO_VLAN_::
  185 	indicates if VLAN discovery should be performed.  If AUTO_VLAN is
  186 	set to "yes", then once the link configuration has been validated,
  187 	*fcoemon* will run run the FIP VLAN discovery protocol on the
  188 	Ethernet interface. Network interfaces for any discovered FCoE
  189 	VLANs will be automatically created, if they are not already
  190 	configured, and FCoE instances will be created on the VLAN
  191 	interfaces.  If the network interface specified by the filename is
  192 	already a VLAN interface, the AUTO_VLAN setting is ignored.
  193 
  194 _MODE_::
  195 	indicates whether operation will be in fabric or vn2vn mode. The
  196 	default is fabric.
  197 
  198 _FIP_RESP_::
  199 	indicates whether a FIP responder should be activated on this
  200 	device to support VLAN discovery in a vn2vn environment. The
  201 	default is "no". Often this will be used on a vn2vn node also
  202 	serving as a target. When using this option, the AUTO_VLAN
  203 	should not be set and the supported VLANs should have
  204 	configuration files supplied, constituting a static VLAN
  205 	configuration that provides the information for the FIP responder
  206 	to return. This should be set on a base device, which should
  207 	probably have FCOE_ENABLE set to "no" since presumably FCoE
  208 	operation will be on the configured VLANs.
  209 
  210 Note that the attached Ethernet peer device (e.g. FCoE capable switch port)
  211 must have compatible settings For DCB and FCoE to function properly.
  212 
  213 /etc/init.d/fcoe
  214 ~~~~~~~~~~~~~~~~
  215 This is the *fcoe* system service script. This script is invoked by the
  216 init process or by the service command to start and stop the *fcoemon*.
  217 On systemd-enabled systems, *fcoemon* is controlled via the *fcoe.service* unit.
  218 
  219 VLAN NAMING CONVENTIONS
  220 -----------------------
  221 If a new VLAN device is created (see the description of the _AUTO_VLAN_
  222 setting above), it will have the name _dev_._vlan_-fcoe; where _dev_ is the
  223 name of the Ethernet parent device and _vlan_ is the discovered VLAN ID
  224 number.
  225 
  226 SEE ALSO
  227 --------
  228 *fcoeadm*(8)
  229 *lldpad*(8)
  230 *lldptool*(8)
  231 *dcbtool*(8)
  232 
  233 SUPPORT
  234 -------
  235 *fcoemon* is part of the _fcoe-utils_ package, maintained through the
  236 _Open-FCoE_ project. Resources for both developers and users can be found
  237 at the _Open-FCoE_ website <http://open-fcoe.org/>