///////////////////////////////////////////////////////////////////////////
// vim:syntax=asciidoc:tw=75:
//
// This is an asciidoc text file, which will be converted into a UNIX man
// page using asciidoc and the DocBook XSL stylesheets.
//
// If you are going to update this documentation, please modify this file
// and then regenerate the nroff formatted man page using the Makefile.
///////////////////////////////////////////////////////////////////////////
FCOEMON(8)
==========
:man source: Open-FCoE
:man manual: Open-FCoE Tools
NAME
----
fcoemon - Open-FCoE service daemon
SYNOPSIS
--------
*fcoemon* [-f|--foreground] [-l|--legacy] [-d|--debug] [-s|--syslog]
*fcoemon* -h|--help
*fcoemon* -v|--version
DESCRIPTION
-----------
The *fcoemon* daemon is the core component of the _Open-FCoE_ management
service.
The primary function of *fcoemon* is to control FCoE instances. *fcoemon*
will create, destroy, reset, enable and disable FCoE instances based on
system configuration, administrative commands, and runtime events.
On startup, *fcoemon* will create FCoE instances defined by the
configuration files (see _FILES_ section below). Since FCoE typically
relies on the Data Center Bridging (DCB) capabilities of an Ethernet
interface, *fcoemon* establishes a connection with the LLDP daemon *lldpad*
to query the status of the DCB features on relevant Ethernet interfaces and
receive DCB configuration change events.
During runtime, *fcoemon* will monitor network and *lldpad* events for the
relevant Ethernet interfaces and perform appropriate actions (create,
destroy, enable, disable) on the FCoE instances. *fcoemon* also provides a
client interface via which the *fcoeadm* utility is able to issue commands.
Installation of the _fcoe-utils_ package will set up an _fcoe_ service which
will control the execution of the *fcoemon* daemon.
OPTIONS
-------
*-f*, *--foreground*::
Run *fcoemon* in the foreground.
*-d*, *--debug*::
Enable debugging messages.
*-l*, *--legacy*::
Force fcoemon to use the legacy /sys/module/libfcoe/parameters/
interface. The default is to use the newer /sys/bus/fcoe/ interfaces
if they are available.
*-s*, *--syslog*::
Use syslogd for logging. The default behavior is to log to stdout
and stderr.
*-h*, *--help*::
Show help message with basic usage instructions
*-v*, *--version*::
Show the version of the *fcoemon* command.
TERMINOLOGY
-----------
_DCB_::
Data Center Bridging A set of Ethernet enhancement standards
developed by the IEEE 802.1 Working Group.
::
See <http://www.ieee802.org/1/pages/dcbridges.html> for more
information.
_DCBX_::
DCB Capabilities Exchange Protocol, implemented by the DCB module
of *lldpad*. DCBX exchanges DCB capabilities and configuration with
a link partner as a series of values transferred using the Link Layer
Discovery Protocol (LLDP).
_PFC_::
Priority-based Flow Control, a _DCB_ feature.
_App:FCoE_::
The FCoE instance of application specific parameters in DCBX.
CRITERIA USED FOR CONTROLLING THE FCOE INSTANCE
-----------------------------------------------
*fcoemon* uses two information sources for determining when to create an
FCoE instance: the state of the network interface, which may be a VLAN
interface, and, if required for the FCoE instance, the state of the DCB
configuration on the physical Ethernet interface.
First of all, the network interface must be "up" for the FCoE instance to
be created. Secondly, if the FCoE configuration indicates that DCB is
required, then the following criteria must be satisfied before the FCoE
interface is created:
* DCB is enabled on the Ethernet interface.
* The PFC DCB feature is enabled and operational.
* The App:FCoE DCB feature is enabled and operational.
* The priority indicated by the App:FCoE feature is also enabled for PFC.
Once the FCoE instance is created by *fcoemon*, it will only be destroyed
under the following conditions:
* The driver for the Ethernet interface is unloaded.
* A user administratively destroys the FCoE instance using *fcoeadm*.
* The *fcoemon* daemon is terminated.
If DCB is required for the FCoE instance, and the DCB settings change after
the interface is created, the following criteria are used to disable the
FCoE instance:
* DCB is disabled on the Ethernet interface.
* The App:FCoE DCB feature is not enabled.
* The App:FCoE and PFC features are operational AND the priority indicated
by App:FCoE is not enabled for PFC.
Otherwise, the FCoE instance will always remain enabled.
CONFIGURATION
-------------
Once the _fcoe-utils_ and *lldpad* packages have been installed and the
corresponding services are running, there are a few simple configuration
steps required to get an FCoE instance up and running. The following
assumes that DCB will be required for the interface.
* Ensure that the configuration on the peer device (e.g. FCoE capable
switch) has the necessary configurations (VLANs, DCB, DCBX).
* Configure any needed VLAN interfaces on the local system.
* Create and configure _/etc/fcoe/cfg-<ifname>_ files for the network
interfaces over which FCoE instances need to be created. See the _FILES_
sections for details. Note that _ifname_ may be for a VLAN interface.
* Restart the *fcoe* service (i.e. *fcoemon*).
* The default DCB configuration of an Ethernet interface managed by
*lldpad* requires the following configuration using *dcbtool*.
dcbtool sc ethX dcb on <-- enable DCB on the interface
dcbtool sc ethX app:fcoe e:1 <-- enable App:FCoE on the interface
These steps only need to be done one time. Note that if other DCB
configuration changes have been made with *dcbtool*, then additional
changes may need to be made in order to satisfy the DCB criteria for
creating an FCoE instance. Consult *dcbtool* for details.
Once these configuration steps have been performed, use *fcoeadm* to query
the status of the FCoE instances.
FILES
-----
/etc/fcoe/config
~~~~~~~~~~~~~~~~
This is the primary configuration file for the *fcoe* system service. The
default options in this file are: *DEBUG="no"* and *USE_SYSLOG="yes"*. The
former is used to enable debugging messages from the fcoe service script
and *fcoemon* (via the *--debug* option). The latter is to indicate if the
log messages are to be output to the system log (via the *--syslog*
option). *SUPPORTED_DRIVERS* is the list of drivers to automatically load
during fcoe service start. Any changes to this file will require a restart
of the *fcoe* service.
/etc/sysconfig/fcoe
~~~~~~~~~~~~~~~~~~~
On systemd-enabled systems, this is the primary configuration file used for
the *fcoe* system service. Add *--debug* to *FCOEMON_OPTS* to enable debug
log messages. Any changes to this file will require a restart of the *fcoe*
service.
/etc/fcoe/cfg-<ifname>
~~~~~~~~~~~~~~~~~~~~~~
These files are read by *fcoemon* on initialization. They are used to
indicate which Ethernet or VLAN interfaces should have FCoE instances
created. The option values in this file normally are: *FCOE_ENABLE="yes"*,
*DCB_REQUIRED="yes"*, and *AUTO_VLAN="yes"*, though if the variable
values are omitted, they default to "no".
_FCOE_ENABLE_::
is used to enable/disable creation of the FCoE instance. If
FCoE_ENABLE is set to "no", then the other configuration values
have no effect.
_DCB_REQUIRED_::
indicates if the DCB service is required on the Ethernet interface.
_AUTO_VLAN_::
indicates if VLAN discovery should be performed. If AUTO_VLAN is
set to "yes", then once the link configuration has been validated,
*fcoemon* will run run the FIP VLAN discovery protocol on the
Ethernet interface. Network interfaces for any discovered FCoE
VLANs will be automatically created, if they are not already
configured, and FCoE instances will be created on the VLAN
interfaces. If the network interface specified by the filename is
already a VLAN interface, the AUTO_VLAN setting is ignored.
_MODE_::
indicates whether operation will be in fabric or vn2vn mode. The
default is fabric.
_FIP_RESP_::
indicates whether a FIP responder should be activated on this
device to support VLAN discovery in a vn2vn environment. The
default is "no". Often this will be used on a vn2vn node also
serving as a target. When using this option, the AUTO_VLAN
should not be set and the supported VLANs should have
configuration files supplied, constituting a static VLAN
configuration that provides the information for the FIP responder
to return. This should be set on a base device, which should
probably have FCOE_ENABLE set to "no" since presumably FCoE
operation will be on the configured VLANs.
Note that the attached Ethernet peer device (e.g. FCoE capable switch port)
must have compatible settings For DCB and FCoE to function properly.
/etc/init.d/fcoe
~~~~~~~~~~~~~~~~
This is the *fcoe* system service script. This script is invoked by the
init process or by the service command to start and stop the *fcoemon*.
On systemd-enabled systems, *fcoemon* is controlled via the *fcoe.service* unit.
VLAN NAMING CONVENTIONS
-----------------------
If a new VLAN device is created (see the description of the _AUTO_VLAN_
setting above), it will have the name _dev_._vlan_-fcoe; where _dev_ is the
name of the Ethernet parent device and _vlan_ is the discovered VLAN ID
number.
SEE ALSO
--------
*fcoeadm*(8)
*lldpad*(8)
*lldptool*(8)
*dcbtool*(8)
SUPPORT
-------
*fcoemon* is part of the _fcoe-utils_ package, maintained through the
_Open-FCoE_ project. Resources for both developers and users can be found
at the _Open-FCoE_ website <http://open-fcoe.org/>