Update the content of the fcoeadm and fcoemon man pages, and add a fipvlan man page. This patch now puts the man pages in asciidoc format, with a Makefile that generates nroff man pages using asciidoc and the DocBook XSL stylesheets. The generated nroff pages are also checked into source control, as users shouldn't need to have the asciidoc and DocBook tools installed to generate them.
Signed-off-by: Chris Leech <[email protected]> --- Makefile.am | 2 doc/Makefile | 22 ++ doc/fcoeadm.8 | 353 +++++++++++++++++++++++++-------------- doc/fcoeadm.txt | 162 ++++++++++++++++++ doc/fcoemon.8 | 496 ++++++++++++++++++++++++++++++++++++++----------------- doc/fcoemon.txt | 216 ++++++++++++++++++++++++ doc/fipvlan.8 | 100 +++++++++++ doc/fipvlan.txt | 94 ++++++++++ 8 files changed, 1163 insertions(+), 282 deletions(-) create mode 100644 doc/Makefile create mode 100644 doc/fcoeadm.txt create mode 100644 doc/fcoemon.txt create mode 100644 doc/fipvlan.8 create mode 100644 doc/fipvlan.txt diff --git a/Makefile.am b/Makefile.am index a149705..fa0f82e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -44,7 +44,7 @@ fcoe_configdir = ${sysconfdir}/fcoe dist_fcoe_config_DATA = etc/cfg-ethx ## man pages for fcoeadm and fcoemon -dist_man_MANS = doc/fcoeadm.8 doc/fcoemon.8 +dist_man_MANS = doc/fcoeadm.8 doc/fcoemon.8 doc/fipvlan.8 ## init script for fcoemon dist_noinst_SCRIPTS = etc/initd/initd.suse etc/initd/initd.fedora \ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..09c3c6a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,22 @@ +## known to work with asciidoc version 8.4.5 +## and the DocBook XSL Stylesheets version 1.75.2 + +MAN_8_TXT := fcoeadm.txt fcoemon.txt fipvlan.txt +MAN_TXT := $(MAN_8_TXT) +MAN_8 := $(patsubst %.txt,%.8,$(MAN_8_TXT)) +MAN := $(MAN_8) +MAN_XML := $(patsubst %.txt,%.xml,$(MAN_TXT)) + +man: $(MAN) + +XSLTPROC_OPTS := --param man.justify 1 +A2X_OPTS := -d manpage --xsltproc-opts='$(XSLTPROC_OPTS)' + +%.8: %.txt + a2x -f manpage $(A2X_OPTS) $< + +clean: + rm -f $(MAN_XML) + +.DEFAULT_GOAL := man +.PHONY: man clean diff --git a/doc/fcoeadm.8 b/doc/fcoeadm.8 index 916f263..7aef6ae 100644 --- a/doc/fcoeadm.8 +++ b/doc/fcoeadm.8 @@ -1,131 +1,236 @@ -.TH "FCOEADM" "8" "November 4, 2008" "Open-FCoE Applications" "Open-FCoE Tools" +'\" t +.\" Title: fcoeadm +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 04/01/2010 +.\" Manual: Open-FCoE Tools +.\" Source: Open-FCoE +.\" Language: English +.\" +.TH "FCOEADM" "8" "04/01/2010" "Open\-FCoE" "Open\-FCoE Tools" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- .SH "NAME" -\fBfcoeadm\fR \- The Fibre Channel over Ethernet (FCoE) administration tool +fcoeadm \- The Open\-FCoE Administration Tool .SH "SYNOPSIS" -\fBfcoeadm\fR [\fB\-c\fR|\fB\-\-create\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-d\fR|\fB\-\-destroy\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-r\fR|\fB\-\-reset\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-i\fR|\fB\-\-interface\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-t\fR|\fB\-\-target\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-l\fR|\fB\-\-lun\fR] [\fI<ethX>\fR] -.P -\fBfcoeadm\fR [\fB\-s\fR|\fB\-\-stats\fR \fI<ethX>\fR [\fI<interval>\fR]] -.P -\fBfcoeadm\fR [\fB\-v\fR|\fB\-\-version\fR] -.P -\fBfcoeadm\fR [\fB\-h\fR|\fB\-\-help\fR] +.sp +\fBfcoeadm\fR \-c|\-\-create \fIethX\fR +.sp +\fBfcoeadm\fR \-d|\-\-destroy \fIethX\fR +.sp +\fBfcoeadm\fR \-r|\-\-reset \fIethX\fR +.sp +\fBfcoeadm\fR \-i|\-\-interface [\fIethX\fR] +.sp +\fBfcoeadm\fR \-t|\-\-target [\fIethX\fR] +.sp +\fBfcoeadm\fR \-l|\-\-lun [\fIethX\fR] +.sp +\fBfcoeadm\fR \-s|\-\-stats \fIethX\fR [\fIinterval\fR] +.sp +\fBfcoeadm\fR \-h|\-\-help +.sp +\fBfcoeadm\fR \-v|\-\-version .SH "DESCRIPTION" -The \fBfcoeadm\fR command is intended to be the FCoE management tool for the Linux systems. -The \fB\-c\fR, \fB\-d\fR, and \fB\-r\fR options are used to create, destroy, and reset -an FCoE instance on a given network interface. The other options are used to query the -information of the FCoE instance which includes the interface information, target information, -LUN information, and port statistics. The \fBfcoeadm\fR command invokes the \fBHBAAPI\fR library -routines to obtain these information. The \fBHBAAPI\fR library routines invoke the vendor\-specific -library, \fBlibhbalinux\fR, to grab the information from the /sys file system. In other words, -the \fBfcoeadm\fR command requires to have \fBlibHBAAPI\fR and \fBlibhbalinux\fR installed on the system to work. -The \fBlibhbalinux\fR is maintained at \fB\fIwww.Open\-FCoE.org\fR. The installation instructions of -\fBlibhbalinux\fR also instructs how to download the \fBHBAAPI\fR source code, build and install with -the \fBlibhbalinux\fR. The last option \fB\-h\fR is used to show a brief usage message of the supported -command syntax. +.sp +The \fBfcoeadm\fR utility is the Fibre Channel over Ethernet (FCoE) management tool for the \fIOpen\-FCoE\fR project\&. \fBfcoeadm\fR may be used to create, destroy, and reset an FCoE instance on a given network interface\&. For these operations \fBfcoeadm\fR sends a command to a running \fBfcoemon\fR process, via a socket interface\&. \fBfcoemon\fR will then perform the requested operation\&. +.sp +\fBfcoeadm\fR also provides options to query information about FCoE instances, including interface information, target information, LUN information, and port statistics\&. For much of this information, \fBfcoeadm\fR relies on the \fIlibhbalinux\fR implementation of the \fIHBA API\fR\&. .SH "OPTIONS" -.TP -\fB\-c\fR, \fB\-\-create\fR \fI<ethX>\fR -Creates an FCoE instance based on the given \fI<ethX>\fR. -.TP -\fB\-d\fR, \fB\-\-destroy\fR \fI<ethX>\fR -Destroys an FCoE instance based on the given \fI<ethX>\fR. -.TP -\fB\-r\fR, \fB\-\-reset\fR \fI<ethX>\fR -Resets the fc_host associated with the FCoE interface given by \fI<ethX>\fR. -.TP -\fB\-i\fR, \fB\-\-interface\fR \fI<ethX>\fR -Show the information of the FCoE instance created at \fI<ethX>\fR. -If \fI<ethX>\fR is not specified the command will show the information of all the -FCoE instances created on the system. -.TP -\fB\-t\fR, \fB\-\-target\fR \fI<ethX>\fR -Show the information of all the discovered targets from the FCoE instance created -at \fI<ethX>\fR. If \fI<ethX>\fR is not specified the command will -show the information of all the discovered targets from all the FCoE instances created. -.TP -\fB\-l\fR, \fB\-\-lun\fR \fI<ethX>\fR -Show the information of all the discovered LUNs from the FCoE instance created -at \fI<ethX>\fR. If \fI<ethX>\fR is not specified the command will -show the information of all the discovered LUNs from all the FCoE instances created. -.TP -\fB\-s\fR, \fB\-\-stats\fR \fI<ethX>\fR \fI<interval>\fR -Show the statistics (including FC4 statistics) of the FCoE instances created at \fI<ethX>\fR. -The information will be display in one line on the screen per given time interval. \fI<interval>\fR should -be specified in whole intergers greater than 0. It specifies the time interval in the unit of second. -If \fI<interval>\fR is not specified, the default interval is one second. -.TP -\fB\-v\fR, \fB\-\-version\fR -Displays the version of the \fBfcoeadm\fR command. -.TP +.PP +\fB\-c\fR, \fB\-\-create\fR \fIethX\fR +.RS 4 +Creates an FCoE instance based on the specified network interface\&. Note that if there is not an fcoemon configuration file for the interface (/etc/fcoe/cfg\-ethX, see +\fBfcoemon\fR), then the created FCoE instance will not require DCB\&. +.RE +.PP +\fB\-d\fR, \fB\-\-destroy\fR \fIethX\fR +.RS 4 +Destroys the FCoE instance on the specified network interface\&. +.RE +.PP +\fB\-r\fR, \fB\-\-reset\fR \fIethX\fR +.RS 4 +Resets the FCoE instance on the specified network interface\&. +.RE +.PP +\fB\-i\fR, \fB\-\-interface\fR [\fIethX\fR] +.RS 4 +Show information about the FCoE instance on the specified network interface, or all FCoE instances if no network interface is specified\&. +.RE +.PP +\fB\-t\fR, \fB\-\-target\fR [\fIethX\fR] +.RS 4 +Show information about the discovered targets associated with the FCoE instance on the specified network interface\&. If no network interface is specified, information about discovered targets from all FCoE instances will be shown\&. +.RE +.PP +\fB\-l\fR, \fB\-\-lun\fR [\fIethX\fR] +.RS 4 +Show detailed information about the discovered SCSI LUNs associated with the FCoE instance on the specified network interface\&. If no network interface is specifed, information about SCSI LUNs from all FCoE instances will be shown\&. +.RE +.PP +\fB\-s\fR, \fB\-\-stats\fR \fIethX\fR [\fIinterval\fR] +.RS 4 +Show the statistics (including FC4 statistics) of the FCoE interface on the specfied network interface\&. The information will be display in one line on the screen per given time interval\&. +\fIinterval\fR +should be specified in whole integers greater than 0\&. It specifies the time interval in the unit of seconds\&. If +\fIinterval\fR +is not specified, the default interval is one second\&. +.RE +.PP \fB\-h\fR, \fB\-\-help\fR -Displays the usage message of the \fBfcoeadm\fR command. -.TP -where \fI<ethX>\fR is the network interface name, such as eth0, eth1, etc. +.RS 4 +Displays the usage message of the +\fBfcoeadm\fR +command\&. +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Displays the version of the +\fBfcoeadm\fR +command\&. +.RE .SH "EXAMPLES" -Creates an FCoE instance on eth2 -.IP -$ \fBfcoeadm\fR \-c eth2 -.P -Destroys the FCoE instance on eth2 -.IP -$ \fBfcoeadm\fR \-d eth2 -.P -Resets the FCoE instance on eth2 -.IP -$ \fBfcoeadm\fR \-r eth2 -.P -Show the information of all the adapters and their ports having FCoE instances created. -.IP -$ \fBfcoeadm\fR \-i -.P -Show the information of a specific interface eth3. If eth3 has no FCoE instances created, -the command will show the error "No fc_host found for eth3". -.IP -$ \fBfcoeadm\fR \-i eth3 -.P -Show the information of all the discovered targets from all the ports having FCoE instances -created (they may be on different adapter cards). A brief listing of discovered LUNs are -listed after the target they are associated with, if any. -.IP -$ \fBfcoeadm\fR \-t -.P -Show the information of all the discovered targets from a given port (eth3) having FCoE instance -created. A brief listing of discovered LUNs are listed after each target they are associated with, if any. -.IP -$ \fBfcoeadm\fR \-t eth3 -.P -Show the detailed information of all the LUNs discovered on all FCoE connections. -.IP -$ \fBfcoeadm\fR \-l -.P -Show the detailed information of all the LUNs associated with a specific interface. -.IP -$ \fBfcoeadm\fR \-l eth3.101 -.P -Show the statistics information of a specific port eth3 having FCoE instances created. -The statistics are displayed one line per time interval. The default interval is one -second if an interval is not specified. -.IP -$ \fBfcoeadm\fR \-s eth3 -.P -.IP -$ \fBfcoeadm\fR \-s eth3 3 -.SH "REPORTING BUGS" -If you have identified a -defect please either file a bug or engage the development mailing list at -<http://www.Open\-FCoE.org>. +.sp +Creates an FCoE instance on eth2\&.101 +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-c eth2\&.101 +.fi +.if n \{\ +.RE +.\} +.sp +Destroys the FCoE instance on eth2\&.101 +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-d eth2\&.101 +.fi +.if n \{\ +.RE +.\} +.sp +Resets the FCoE instance on eth2\&.101 +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-r eth2\&.101 +.fi +.if n \{\ +.RE +.\} +.sp +Show the information of all the adapters and their ports having FCoE instances created +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-i +.fi +.if n \{\ +.RE +.\} +.sp +Show the information of a specific interface eth3\&. If eth3 has no FCoE instances created, the command will show the error "No fc_host found for eth3" +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-i eth3 +.fi +.if n \{\ +.RE +.\} +.sp +Show the information of all the discovered targets from all the ports having FCoE instances created (they may be on different adapter cards)\&. A brief listing of discovered LUNs are listed after the target they are associated with, if any +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-t +.fi +.if n \{\ +.RE +.\} +.sp +Show the information of all the discovered targets from a given port (eth3) having FCoE instance created\&. A brief listing of discovered LUNs are listed after each target they are associated with, if any +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-t eth3 +.fi +.if n \{\ +.RE +.\} +.sp +Show the detailed information of all the LUNs discovered on all FCoE connections +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-l +.fi +.if n \{\ +.RE +.\} +.sp +Show the detailed information of all the LUNs associated with a specific interface +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-l eth3\&.101 +.fi +.if n \{\ +.RE +.\} +.sp +Show the statistics information of a specific port eth3 having FCoE instances created\&. The statistics are displayed one line per time interval\&. The default interval is one second if an interval is not specified +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-s eth3 +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +fcoeadm \-s eth3 3 +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.sp +\fBfcoemon\fR(8) .SH "SUPPORT" -Open\-FCoE is maintained at <http://www.Open\-FCoE.org>. There are resources -available for both developers and users at that site. - - +.sp +\fBfcoeadm\fR is part of the \fIfcoe\-utils\fR package, maintained through the \fIOpen\-FCoE\fR project\&. Resources for both developers and users can be found at the \fIOpen\-FCoE\fR website http://open\-fcoe\&.org/ diff --git a/doc/fcoeadm.txt b/doc/fcoeadm.txt new file mode 100644 index 0000000..0bd73cf --- /dev/null +++ b/doc/fcoeadm.txt @@ -0,0 +1,162 @@ +/////////////////////////////////////////////////////////////////////////// +// 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 formated man page using the Makefile. +/////////////////////////////////////////////////////////////////////////// + +FCOEADM(8) +========== +:man source: Open-FCoE +:man manual: Open-FCoE Tools + +NAME +---- +fcoeadm - The Open-FCoE Administration Tool + +SYNOPSIS +-------- +*fcoeadm* -c|--create _ethX_ + +*fcoeadm* -d|--destroy _ethX_ + +*fcoeadm* -r|--reset _ethX_ + +*fcoeadm* -i|--interface [_ethX_] + +*fcoeadm* -t|--target [_ethX_] + +*fcoeadm* -l|--lun [_ethX_] + +*fcoeadm* -s|--stats _ethX_ [_interval_] + +*fcoeadm* -h|--help + +*fcoeadm* -v|--version + +DESCRIPTION +----------- +The *fcoeadm* utility is the Fibre Channel over Ethernet (FCoE) management +tool for the _Open-FCoE_ project. *fcoeadm* may be used to create, +destroy, and reset an FCoE instance on a given network interface. For these +operations *fcoeadm* sends a command to a running *fcoemon* process, via a +socket interface. *fcoemon* will then perform the requested operation. + +*fcoeadm* also provides options to query information about FCoE instances, +including interface information, target information, LUN information, and port +statistics. For much of this information, *fcoeadm* relies on the _libhbalinux_ +implementation of the _HBA API_. + +OPTIONS +------- +*-c*, *--create* _ethX_:: + Creates an FCoE instance based on the specified network interface. + Note that if there is not an fcoemon configuration file for the + interface (/etc/fcoe/cfg-ethX, see *fcoemon*), then the created + FCoE instance will not require DCB. + +*-d*, *--destroy* _ethX_:: + Destroys the FCoE instance on the specified network interface. + +*-r*, *--reset* _ethX_:: + Resets the FCoE instance on the specified network interface. + +*-i*, *--interface* [_ethX_]:: + Show information about the FCoE instance on the specified network + interface, or all FCoE instances if no network interface is specified. + +*-t*, *--target* [_ethX_]:: + Show information about the discovered targets associated with the + FCoE instance on the specified network interface. + If no network interface is specified, information about discovered + targets from all FCoE instances will be shown. + +*-l*, *--lun* [_ethX_]:: + Show detailed information about the discovered SCSI LUNs associated + with the FCoE instance on the specified network interface. + If no network interface is specifed, information about SCSI LUNs + from all FCoE instances will be shown. + +*-s*, *--stats* _ethX_ [_interval_]:: + Show the statistics (including FC4 statistics) of the FCoE + interface on the specfied network interface. + The information will be display in one line on the screen per given + time interval. _interval_ should be specified in whole integers + greater than 0. It specifies the time interval in the unit of + seconds. If _interval_ is not specified, the default interval is + one second. + +*-h*, *--help*:: + Displays the usage message of the *fcoeadm* command. + +*-v*, *--version*:: + Displays the version of the *fcoeadm* command. + +EXAMPLES +-------- +Creates an FCoE instance on eth2.101 + + fcoeadm -c eth2.101 + +Destroys the FCoE instance on eth2.101 + + fcoeadm -d eth2.101 + +Resets the FCoE instance on eth2.101 + + fcoeadm -r eth2.101 + +Show the information of all the adapters and their ports having FCoE +instances created + + fcoeadm -i + +Show the information of a specific interface eth3. If eth3 has no FCoE +instances created, the command will show the error "No fc_host found for +eth3" + + fcoeadm -i eth3 + +Show the information of all the discovered targets from all the ports +having FCoE instances created (they may be on different adapter cards). +A brief listing of discovered LUNs are listed after the target they are +associated with, if any + + fcoeadm -t + +Show the information of all the discovered targets from a given port (eth3) +having FCoE instance created. A brief listing of discovered LUNs are listed +after each target they are associated with, if any + + fcoeadm -t eth3 + +Show the detailed information of all the LUNs discovered on all FCoE +connections + + fcoeadm -l + +Show the detailed information of all the LUNs associated with a specific +interface + + fcoeadm -l eth3.101 + +Show the statistics information of a specific port eth3 having FCoE +instances created. The statistics are displayed one line per time interval. +The default interval is one second if an interval is not specified + + fcoeadm -s eth3 + + fcoeadm -s eth3 3 + +SEE ALSO +-------- +*fcoemon*(8) + +SUPPORT +------- +*fcoeadm* 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/> diff --git a/doc/fcoemon.8 b/doc/fcoemon.8 index 80e3f58..0ff3637 100644 --- a/doc/fcoemon.8 +++ b/doc/fcoemon.8 @@ -1,164 +1,346 @@ -.TH "FCOEMON" "8" "December 22, 2008" "Open-FCoE Applications" "Open-FCoE Tools" +'\" t +.\" Title: fcoemon +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 04/01/2010 +.\" Manual: Open-FCoE Tools +.\" Source: Open-FCoE +.\" Language: English +.\" +.TH "FCOEMON" "8" "04/01/2010" "Open\-FCoE" "Open\-FCoE Tools" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- .SH "NAME" -\fBfcoemon\fR \- The Fibre Channel over Ethernet (FCoE) administration tool - for monitoring and processing events from the DCB daemon (\fBdcbd\fR). +fcoemon \- Open\-FCoE service daemon .SH "SYNOPSIS" -\fBfcoemon\fR [\fB\-h\fR | \fB\-\-help\fR] -.P -\fBfcoemon\fR [\fB\-v\fR | \fB\-\-version\fR] -.P -\fBfcoemon\fR [\fB\-f\fR | \fB\-\-foreground\fR] -.P -\fBfcoemon\fR [\fB\-d\fR | \fB\-\-debug\fR] -.P -\fBfcoemon\fR [\fB\-s\fR | \fB\-\-syslog\fR] +.sp +\fBfcoemon\fR [\-f|\-\-foreground] [\-d|\-\-debug] [\-s|\-\-syslog] +.sp +\fBfcoemon\fR \-h|\-\-help +.sp +\fBfcoemon\fR \-v|\-\-version .SH "DESCRIPTION" -The \fBfcoemon\fR command is a FCoE management tool provided by the \fBfcoe-utils\fR package. -\fBfcoemon\fR is the daemon of the \fBfcoe\fR system service. When \fBfcoemon\fR starts, it establishes a socket -connection with the DCB daemon (\fBdcbd\fR). It then sends commands to, and receives responses -and events from \fBdcbd\fR. \fBfcoemon\fR will process the responses -and events and will create or destroy the FCoE interfaces as needed. -Since \fBfcoemon\fR can depend on \fBdcbd\fR, there may be settings required for \fBdcbd\fR before \fBfcoemon\fR can be started. See the \fIDCB Settings\fR section below. - -The \fBfcoe\fR system may or may not depend on the DCB service. \fBfcoemon\fR will be -started by the \fBfcoe\fR service only if one of the Ethernet ports requires DCB, as specified by the \fBfcoe\fR per-interface configuration files. If no Ethernet ports require DCB then \fBfcoemon\fR will not be started and the \fBfcoe\fR service will not depend on \fBdcbd\fR. - +.sp +The \fBfcoemon\fR daemon is the core component of the \fIOpen\-FCoE\fR management service\&. +.sp +The primary function of \fBfcoemon\fR is to control FCoE instances\&. \fBfcoemon\fR will create, destroy, reset, enable and disable FCoE instances based on system configuration, administrative commands, and runtime events\&. +.sp +On startup, \fBfcoemon\fR will create FCoE instances defined by the configuration files (see \fIFILES\fR section below)\&. Since FCoE typically relies on the Data Center Bridging (DCB) capabilities of an Ethernet interface, \fBfcoemon\fR establishes a connection with the LLDP daemon \fBlldpad\fR to query the status of the DCB features on relevant Ethernet interfaces and receive DCB configuration change events\&. +.sp +During runtime, \fBfcoemon\fR will monitor network and \fBlldpad\fR events for the relevant Ethernet interfaces and perform appropriate actions (create, destroy, enable, disable) on the FCoE instances\&. \fBfcoemon\fR also privides a client interface via which the \fBfcoeadm\fR utility is able to issue commands\&. +.sp +Instalation of the \fIfcoe\-utils\fR package will set up an \fIfcoe\fR service which will control the execution of the \fBfcoemon\fR daemon\&. .SH "OPTIONS" -.TP -\fB\-h | \-v | \-\-version\fR -Show the version of the \fBfcoemon\fR command. -.TP -\fB\-f | \-\-foreground\fR -Run \fBfcoemon\fR in the foreground. -.TP -\fB\-d | \-\-debug\fR -Enable debugging messages. -.TP -\fB\-s | \-\-syslog\fR -Use syslogd for logging. The default behavior is to log to stdout and stderr. +.PP +\fB\-f\fR, \fB\-\-foreground\fR +.RS 4 +Run +\fBfcoemon\fR +in the foreground\&. +.RE +.PP +\fB\-d\fR, \fB\-\-debug\fR +.RS 4 +Enable debugging messages\&. +.RE +.PP +\fB\-s\fR, \fB\-\-syslog\fR +.RS 4 +Use syslogd for logging\&. The default behavior is to log to stdout and stderr\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show help message with basic usage instructions +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Show the version of the +\fBfcoemon\fR +command\&. +.RE .SH "TERMINOLOGY" -.TP -\fBPFC\fR \- The DCB Priority Flow Control feature. -.TP -\fBApp:FCoE\fR \- The DCB Fibre Channel over Ethernet feature. -.TP -\fBLLINK\fR \- The DCB Logical Link TLV (or Logical Link) feature. -.TP -\fBmultiq\fR \- See Documentation/networking/multiqueue.txt of linux kernel source, v2.6.28 or higher. -.TP -\fBskbedit\fR \- See Documentation/networking/multiqueue.txt of linux kernel source v2.6.28 or higher. -.SH "INSTALLATION REQUIREMENTS" -The DCB and FCoE kernel configuration options must be enabled, these were introduced in the kernel version v2.6.29. Both the linux kernel and iproute2 must support multiq and skbedit. The DCB package must be installed with version 0.9.4 and higher. -.SH "SUPPORTED DCB EVENTS" -In response to each supported event from \fBdcbd\fR, \fBfcoemon\fR collects the current -settings from \fBdcbd\fR to decide whether to delete and/or re-add the multiq queue discipline -and skbedit filter. -.TP -\fBFEATURE_APP\fR -If an event message is received from dcbd and if the feature code in the event message -is FEATURE_APP (5), and if the subtype field is APP_FCOE_STYPE (0), we got a mode or -configuration change event of the FCoE application. \fBfcoemon\fR will then issue queries -to the DCB daemon to collect the current mode and configuration information. -.TP -\fBFEATURE_PFC\fR -If an event message is received from dcbd and if the feature code in the event message -is FEATURE_PFC (3), we got a mode or configuration change event of the Priority Flow -Control (PFC) feature. The \fBfcoemon\fR will then issue queries to the DCB daemon to collect -the current mode and configuration information. -.TP -\fBFEATURE_LLINK\fR -If an event message is received from dcbd and if the feature code in the event message -is FEATURE_LLINK (6), and if the subtype field is LLINK_FCOE_STYPE (0), we got a mode -or configuration change event of the Logical Link TLV feature. The \fBfcoemon\fR will then -issue queries to the DCB daemon to collect the current mode and configuration information. -.SH "CRITERIA OF CREATING, RESETTING AND DESTROYING FCOE INTERFACE" -In this section the \fBdcbtool\fR is used to describe the conditions of the DCB feture status -beccause the meaning is more understandable and precise. Although you may also issue the -commands at run-time, the commands are intended only to be used for description purpose. -.TP -\fBPFC and App:FCoE\fR -DCB is configured correctly if -.RS -.PD 0 -.TP 3 -.BR "1)" " The command \fBdcbtool gc ethX dcb\fR shows DCB State: on" -.TP 3 -.BR "2)" " The command \fBdcbtool gc ethX app:0\fR shows Enable:true," -.TP 3 -.BR " " " Advertise:true, Willing:true." -.TP 3 -.BR "3)" " The command \fBdcbtool go ethX app:0\fR shows OperMode:true." -.TP 3 -.BR "4)" " The command \fBdcbtool go ethX pfc\fR shows OperMode:true and" -.TP 3 -.BR " " " the values of pfcup." -.TP 3 -.BR "5)" " The command \fBdcbtool go ethX app:0\fR shows appcfg. The bits" -.TP 3 -.BR " " " set to 1 are also set to 1 in pfcup found in (4)." -.PD -.RE -.TP -\fBLogical Link TLV\fR -The Logical Link TLV feature is configured correctly if -.RS -.PD 0 -.TP 3 -.BR "1)" " The command \fBdcbtool gc ethX ll:0\fR shows" -.TP 3 -.BR " " " Enable:true, Advertise:true, Willing:true." -.TP 3 -.BR "2)" " The command \fBdcbtool go ethX ll:0\fR shows OperMode:true." -.TP 3 -.BR "3)" " The command \fBdbtool gp ethX ll:0\fR shows Link Status:up." -.PD -.RE -.TP -\fBCriteria to create FCoE interface\fR -If DCB is required at the Ethernet port, an FCoE interface may be created only if -the DCB is configured correctly. If DCB is not -required at the Ethernet port, the FCoE interface may be created. -.TP -\fBCriteria to Destroy FCoE Interface\fR -An FCoE interface will only be destroyed when the \fBfcoe\fR system service is stopped. -.TP -\fBChanging DCB Configuration, Qdisc and Filters\fR -Changing the DCB configuration, qdisc, and filter are considered to be administrative actions. -When the \fBfcoe\fR system service starts up, it sets up the default DCB configuration, qdisc, and filter -for reliable FCoE operations. Administrators may alter the configuration while the service is running. -Changing the DCB parameters may cause the \fBfcoemon\fR daemon to delete the existing multiq queue discipline, -skbedit filter and re-add; but the \fBfcoe\fR service will not touch (e.g. destroy or reset) the FCoE interface. -Changing the DCB configuration, qdisc, and filter should be avoided while I/O traffic are in progress. +.PP +\fIDCB\fR +.RS 4 +Data Center Bridging A set of Ethernet enchancement standards developed by the IEEE 802\&.1 Working Group\&. +.RE +.PP +\ \& +.RS 4 +See +http://www\&.ieee802\&.org/1/pages/dcbridges\&.html +for more information\&. +.RE +.PP +\fIDCBX\fR +.RS 4 +DCB Capabilitues Exchange Protocol, implemented by the DCB module of +\fBlldpad\fR\&. DCBX exchanges DCB capabilities and configuration with a link partner as a series of values tranfered using the Link Layer Discovery Protocol (LLDP)\&. +.RE +.PP +\fIPFC\fR +.RS 4 +Priority\-based Flow Control, a +\fIDCB\fR +feature\&. +.RE +.PP +\fIApp:FCoE\fR +.RS 4 +The FCoE instance of application specific parameters in DCBX\&. +.RE +.SH "CRITERIA USED FOR CONTROLLING THE FCOE INSTANCE" +.sp +\fBfcoemon\fR 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\&. +.sp +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 satisified before the FCoE interface is created: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +DCB is enabled on the Ethernet interface\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The PFC DCB feature is enabled and operational\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The App:FCoE DCB feature is enabled and operational\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The priority indicated by the App:FCoE feature is also enabled for PFC\&. +.RE +.sp +Once the FCoE instance is created by \fBfcoemon\fR, it will only be destroyed under the following conditions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The driver for the Ethernet interface is unloaded\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A user administratively destroys the FCoE instance using +\fBfcoeadm\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +\fBfcoemon\fR +daemon is terminated\&. +.RE +.sp +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: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +DCB is disabled on the Ethernet interface\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The App:FCoE DCB feature is not enabled\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The App:FCoE and PFC features are operational AND the priority indicated by App:FCoE is not enabled for PFC\&. +.RE +.sp +Otherwise, the FCoE instance will remain enabled, but certain DCB configurations that may be problematic will generate warning messages in the log\&. +.SH "CONFIGURATION" +.sp +Once the \fIfcoe\-utils\fR and \fBlldpad\fR 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\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Ensure that the configuration on the peer device (e\&.g\&. FCoE capable switch) has the necessary configurations (VLANs, DCB, DCBX)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Configure any needed VLAN interfaces on the local system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Create and configure +\fI/etc/fcoe/cfg\-<ifname>\fR +files for the network interfaces over which FCoE instances need to be created\&. See the +\fIFILES\fR +sections for details\&. Note that +\fIifname\fR +may be for a VLAN interface\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Restart the +\fBfcoe\fR +service (i\&.e\&. +\fBfcoemon\fR)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The default DCB configuration of an Ethernet interface managed by +\fBlldpad\fR +requires the following configuration using +\fBdcbtool\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +dcbtool sc ethX dcb on <\-\- enable DCB on the interface +dcbtool sc ethX app:fcoe e:1 <\-\- enable App:FCoE on the interface +.fi +.if n \{\ +.RE +.\} +.RE +.sp +These steps only need to be done one time\&. Note that if other DCB configuration changes have been made with \fBdcbtool\fR, then additional changes may need to be made in order to satisfy the DCB criteria for creating an FCoE instance\&. Consult \fBdcbtool\fR for details\&. +.sp +Once these configuration steps have been performed, use \fBfcoeadm\fR to query the status of the FCoE instances\&. .SH "FILES" -Installation of the fcoe-utils management tools include the following files: -.TP -\fI/etc/fcoe/config\fR -This is the primary configuration file for the \fBfcoe\fR system service. The default options in this file are: \fBDEBUG="no"\fR and \fBUSE_SYSLOG="yes"\fR. The former is used to enable -debugging messages from the \fBfcoe\fR service script and \fBfcoemon\fR. The latter is -to indicate if the log messages are to be output to the system log. Any changes to this file will require a restart of the \fBfcoe\fR service. -.TP -\fI/etc/fcoe/cfg-<ifname>\fR -This file will be read by the \fI/etc/init.d/fcoe\fR script and the \fBfcoemon\fR daemon. The default options in this file are: -\fBFCOE_ENABLE="no"\fR and \fBDCB_REQUIRED="yes"\fR. The former is used to enable/disable the FCoE service at the ethX port. The latter is to indicate if the DCB service -is required (select yes) or not required (select no) at the ethX port. If the former is set to no, the -latter is ignored. The selection of the settings should match the settings of the FCoE switch port connected -to the local Ethernet ethX port. Use an editor to set the desired \fByes/no\fR -values for the \fBethX\fR interfaces. -.TP -\fI/etc/init.d/fcoe\fR -This is the \fBfcoe\fR system service shell script. This script is invoked by the \fBinit\fR process -or by the \fBservice\fR command. -.TP -\fI/sbin/fcoemon\fR -This is the \fBfcoemon\fR daemon only invoked by the \fBfcoe\fR system service script. -.TP -\fI/sbin/fcoeadm\fR -This is the program used by the \fBfcoe\fR system service to create or destroy FCoE interfaces. -.SH "REPORTING BUGS" -If you have identified a defect please file a bug with your distribution or engage the -development mailing list at <http://www.Open\-FCoE.org>. +.SS "/etc/fcoe/config" +.sp +This is the primary configuration file for the \fBfcoe\fR system service\&. The default options in this file are: \fBDEBUG="no"\fR and \fBUSE_SYSLOG="yes"\fR\&. The former is used to enable debugging messages from the fcoe service script and \fBfcoemon\fR (via the \fB\-\-debug\fR option)\&. The latter is to indicate if the log messages are to be output to the system log (via the \fB\-\-syslog\fR option)\&. Any changes to this file will require a restart of the \fBfcoe\fR service\&. +.SS "/etc/fcoe/cfg\-<ifname>" +.sp +These files are read by \fBfcoemon\fR on initialization\&. They are used to indicate which Ethernet or VLAN interfaces should have FCoE instances created\&. The default options in this file are: \fBFCOE_ENABLE="yes"\fR, \fBDCB_REQUIRED="yes"\fR, and \fBAUTO_VLAN="yes"\fR\&. +.PP +\fIFCOE_ENABLE\fR +.RS 4 +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\&. +.RE +.PP +\fIDCB_REQUIRED\fR +.RS 4 +indicates if the DCB service is required on the Ethernet interface\&. +.RE +.PP +\fIAUTO_VLAN\fR +.RS 4 +indictaes if VLAN discovery should be performed\&. If AUTO_VLAN is set to "yes", then once the link configuration has been validated, +\fBfcoemon\fR +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\&. +.RE +.sp +Note that the attached Ethernet peer device (e\&.g\&. FCoE capable switch port) must have compatible settings For DCB and FCoE to function properly\&. +.SS "/etc/init\&.d/fcoe" +.sp +This is the \fBfcoe\fR system service script\&. This script is invoked by the init process or by the service command to start and stop the \fBfcoemon\fR\&. +.SH "VLAN NAMING CONVENTIONS" +.sp +If a new VLAN device is created (see the desription of the \fIAUTO_VLAN\fR setting above), it will have the name \fIdev\fR\&.\fIvlan\fR\-fcoe; where \fIdev\fR is the name of the Ethernet parent device and \fIvlan\fR is the discovered VLAN ID number\&. +.SH "SEE ALSO" +.sp +\fBfcoeadm\fR(8) \fBlldpad\fR(8) \fBlldptool\fR(8) \fBdcbtool\fR(8) .SH "SUPPORT" -Open\-FCoE is maintained at <http://www.Open\-FCoE.org>. There are resources -available for both developers and users at that site. - - +.sp +\fBfcoemon\fR is part of the \fIfcoe\-utils\fR package, maintained through the \fIOpen\-FCoE\fR project\&. Resources for both developers and users can be found at the \fIOpen\-FCoE\fR website http://open\-fcoe\&.org/ diff --git a/doc/fcoemon.txt b/doc/fcoemon.txt new file mode 100644 index 0000000..39c845b --- /dev/null +++ b/doc/fcoemon.txt @@ -0,0 +1,216 @@ +/////////////////////////////////////////////////////////////////////////// +// 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 formated 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] [-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 privides a +client interface via which the *fcoeadm* utility is able to issue commands. + +Instalation 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. +*-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 enchancement standards + developed by the IEEE 802.1 Working Group. + :: + See <http://www.ieee802.org/1/pages/dcbridges.html> for more + information. + +_DCBX_:: + DCB Capabilitues Exchange Protocol, implemented by the DCB module + of *lldpad*. DCBX exchanges DCB capabilities and configuration with + a link partner as a series of values tranfered 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 satisified 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 remain enabled, but certain DCB +configurations that may be problematic will generate warning messages in +the log. + +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). 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 default options in this file are: *FCOE_ENABLE="yes"*, +*DCB_REQUIRED="yes"*, and *AUTO_VLAN="yes"*. + +_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_:: + indictaes 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. + +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*. + +VLAN NAMING CONVENTIONS +----------------------- +If a new VLAN device is created (see the desription 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/> diff --git a/doc/fipvlan.8 b/doc/fipvlan.8 new file mode 100644 index 0000000..74fb30e --- /dev/null +++ b/doc/fipvlan.8 @@ -0,0 +1,100 @@ +'\" t +.\" Title: fipvlan +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> +.\" Date: 04/01/2010 +.\" Manual: Open-FCoE Tools +.\" Source: Open-FCoE +.\" Language: English +.\" +.TH "FIPVLAN" "8" "04/01/2010" "Open\-FCoE" "Open\-FCoE Tools" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +fipvlan \- Fibre Channel over Ethernet VLAN Discovery +.SH "SYNOPSIS" +.sp +\fBfipvlan\fR [\-c|\-\-create] [\-s|\-\-start] \fIinterfaces\fR +.sp +\fBfipvlan\fR \-a|\-\-auto [\-c|\-\-create] [\-s|\-\-start] +.sp +\fBfipvlan\fR \-h|\-\-help +.sp +\fBfipvlan\fR \-v|\-\-version +.SH "DESCRIPTION" +.sp +The \fBfipvlan\fR command performs Fibre Channel over Ethernet (FCoE) Initialization Protocol (FIP) VLAN Discovery over Ethernet interfaces\&. \fBfipvlan\fR can be used as a diagnostic tool to determine which VLANs have FCoE services available on a network, prior to configuring VLAN interfaces and the \fIOpen\-FCoE\fR initiator\&. \fBfipvlan\fR can also be used to create VLAN interfaces as the are discovered, and to start the \fIOpen\-FCoE\fR initiator\&. The \fB\-\-create\fR and \fB\-\-start\fR options are primarily intended to be used as part of an \fIOpen\-FCoE\fR boot solution\&. +.sp +\fBfipvlan\fR takes a list of network interface names to run the VLAN discovery protocol over, or the \fB\-\-auto\fR option to use all available Ethernet interfaces\&. +.SH "OPTIONS" +.PP +\fB\-a\fR, \fB\-\-auto\fR +.RS 4 +Use all Ethernet interfaces currently available +.RE +.PP +\fB\-c\fR, \fB\-\-create\fR +.RS 4 +Create network interfaces for discovered FCoE VLANs\&. If a VLAN device already exists for a discovered VLAN, a new VLAN device will not be created\&. +.RE +.PP +\fB\-s\fR, \fB\-\-start\fR +.RS 4 +Start the +\fIOpen\-FCoE\fR +initiator on discovered FCoE VLANs +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Display a help message with basic usage instructions +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Display the +\fBfipvlan\fR +version string +.RE +.SH "VLAN NAMING CONVENTIONS" +.sp +If a new VLAN device is created, it will have the name \fIdev\fR\&.\fIvlan\fR\-fcoe; where \fIdev\fR is the name of the Ethernet parent device and \fIvlan\fR is the discovered VLAN ID number\&. +.SH "EXAMPLES" +.sp +Display all discoverable VLANs with FCoE services +.sp +.if n \{\ +.RS 4 +.\} +.nf +fipvlan \-\-auto +.fi +.if n \{\ +.RE +.\} +.sp +Discover FCoE VLANs on interface eth2, create VLAN devices and start the \fIOpen\-FCoE\fR initiator +.sp +.if n \{\ +.RS 4 +.\} +.nf +fipvlan \-\-create \-\-start eth2 +.fi +.if n \{\ +.RE +.\} +.sp +In this example if FCoE services were available on VLAN 101 of network interface eth2, then a VLAN interface eth2\&.101\-fcoe would be created and used as the parent device for the initiator\&. +.SH "SEE ALSO" +.sp +\fBfcoeadm\fR(8) \fBfcoemon\fR(8) +.SH "SUPPORT" +.sp +\fBfipvlan\fR is part of the \fIfcoe\-utils\fR package, maintained through the \fIOpen\-FCoE\fR project\&. Resources for both developers and users can be found at the \fIOpen\-FCoE\fR website http://open\-fcoe\&.org/ diff --git a/doc/fipvlan.txt b/doc/fipvlan.txt new file mode 100644 index 0000000..6e894e9 --- /dev/null +++ b/doc/fipvlan.txt @@ -0,0 +1,94 @@ +/////////////////////////////////////////////////////////////////////////// +// 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 formated man page using the Makefile. +/////////////////////////////////////////////////////////////////////////// + +FIPVLAN(8) +========== +:man source: Open-FCoE +:man manual: Open-FCoE Tools + +NAME +---- +fipvlan - Fibre Channel over Ethernet VLAN Discovery + +SYNOPSIS +-------- +*fipvlan* [-c|--create] [-s|--start] _interfaces_ + +*fipvlan* -a|--auto [-c|--create] [-s|--start] + +*fipvlan* -h|--help + +*fipvlan* -v|--version + +DESCRIPTION +----------- +The *fipvlan* command performs Fibre Channel over Ethernet (FCoE) +Initialization Protocol (FIP) VLAN Discovery over Ethernet interfaces. +*fipvlan* can be used as a diagnostic tool to determine which VLANs have +FCoE services available on a network, prior to configuring VLAN interfaces +and the _Open-FCoE_ initiator. *fipvlan* can also be used to create VLAN +interfaces as the are discovered, and to start the _Open-FCoE_ initiator. +The *--create* and *--start* options are primarily intended to be used as +part of an _Open-FCoE_ boot solution. + +*fipvlan* takes a list of network interface names to run the VLAN discovery +protocol over, or the *--auto* option to use all available Ethernet +interfaces. + +OPTIONS +------- +*-a*, *--auto*:: + Use all Ethernet interfaces currently available + +*-c*, *--create*:: + Create network interfaces for discovered FCoE VLANs. If a VLAN + device already exists for a discovered VLAN, a new VLAN device will + not be created. + +*-s*, *--start*:: + Start the _Open-FCoE_ initiator on discovered FCoE VLANs + +*-h*, *--help*:: + Display a help message with basic usage instructions + +*-v*, *--version*:: + Display the *fipvlan* version string + +VLAN NAMING CONVENTIONS +----------------------- +If a new VLAN device is created, 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. + +EXAMPLES +-------- +Display all discoverable VLANs with FCoE services + + fipvlan --auto + +Discover FCoE VLANs on interface eth2, create VLAN devices and start the +_Open-FCoE_ initiator + + fipvlan --create --start eth2 + +In this example if FCoE services were available on VLAN 101 of network +interface eth2, then a VLAN interface eth2.101-fcoe would be created and +used as the parent device for the initiator. + +SEE ALSO +-------- +*fcoeadm*(8) +*fcoemon*(8) + +SUPPORT +------- +*fipvlan* 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/> _______________________________________________ devel mailing list [email protected] http://www.open-fcoe.org/mailman/listinfo/devel
