fcoeadm: pass flags to fcoemon to enable vn2vn mode
[fcoe-utils.git] / QUICKSTART
1 This document is a quickstart guide for a user connected to a Fibre Channel
2 Forwarder (FCF) and not a SW target. It covers the configuration of the kernel
3 and installation and configuration of Data Center Bridging (DCB), the HBA API
4 wrapper library, libhbalinux and fcoe-utils.
5
6 This document was written using Fedora 11 as the installed operating system.
7 The instructions may need adjustments for them to work on other
8 distributions.
9
10 ##
11 # Dependencies
12 ###############
13
14 git://open-fcoe.org/libHBAAPI.git
15 git://open-fcoe.org/libhbalinux.git
16 git://open-fcoe.org/fcoe-utils.git
17
18 ##
19 # Kernel Configuration and Compilation
20 ######################################
21
22 1) Download kernel source
23    There are a number of good choices regarding the most appropriate
24    kernel source for your needs. fcoe-next.git is a repository that may be
25    unstable, but will have the latest code. Downloading a released kernel
26    from kernel.org will give you the most stable kernel, but you'll need to
27    get user space code that matches the kernel version you've chosen. You can
28    get user space code that matches stable kernels on the Open-FCoE.org
29    "Downloads" page or you can pull directly from the git repositories using
30    tags.
31
32 2) Configure the kernel
33    # make menuconfig
34
35    Select the following:
36
37    Networking Support -> Networking Options
38               Data Center Bridging
39               802.1Q VLAN Support
40               GVRP (GARP VLAN Registration Protocol) support
41
42    Networking Support -> Networking Options -> QoS and/or fair queuing
43               Multi Band Priority Queueing (PRIO)
44               Hardware Multiqueue-aware Multi Band Queuing (MULTIQ)
45               Elementary classification (BASIC)
46               Universal 32bit comparisons w/ hashing (U32)
47               Extended Matches
48                         U32 key
49               Actions
50                         SKB Editing
51
52    Device Drivers -> SCSI Device Support -> SCSI Low-level drivers
53               LibFC
54               LibFCoE
55               FCoE
56
57    Enable the block layer
58               Block layer SG support v4
59
60    Device Drivers -> Network Device Support -> Ethernet (10000 Mbit)
61               Intel(R) 10GbE PCI Express adapters support
62               Data Center Bridging (DCB) Support
63
64    [ Replace with desired driver if not using Intel adapter. ]
65
66    Exit Saving Changes
67
68 3) Compile the kernel
69    # make && make modules_install && make install
70
71    If you're going to build fcoe-utils, you can run 'make headers_install'
72    at this stage to skip a later step.
73
74 4) Configure Grub
75    Change the default kernel so that this new kernel is used when booting
76    # reboot
77
78
79 ##
80 # DCB
81 #######
82
83 DEPENDENCIES
84
85 * libnl
86 * libnl-devel
87 * libconfig
88 * libconfig-devel
89 * autoconf
90 * autotools
91 * sysconftool
92 * automake
93 * libtool
94 * gcc-c++
95 * flex
96 * readline-devel
97
98 PROCESS
99
100 1) Obtain the latest source
101
102    git clone git://open-lldp.org/open-lldp
103
104    (note: fcoe-utils versions >= 1.0.20 require an lldpad version >= 0.9.43)
105
106 2) Obtain libconfig version 1.3.2 or greater included in distribution
107    devel packages source can be obtained directly from
108    http://www.hyperrealm.com/libconfig/
109
110 3) Build and install libconfig -- see libconfig documentation
111
112 4) Obtain and install devel netlink library (libnl) version 1.1 or greater
113    included in distribution devel packages source can be obtained directly
114    from http://www.infradead.org/~tgr/libnl/
115
116 5) Bootstrap, configure, make and make install
117    # cd open-lldp
118    # ./bootstrap.sh
119    # rpm --eval "%configure" | sh
120    # make
121    # make install
122
123
124 ##
125 # HBA API Wrapper Library
126 ##########################
127
128 DEPENDENCIES
129
130 * autoconf
131 * autotools
132 * sysconftool
133 * automake
134 * libtool
135
136 PROCESS
137
138 1) Obtain the latest source
139
140    git clone git://open-fcoe.org/libHBAAPI.git
141
142 2) Bootstrap, configure, make and make install
143    # cd libHBAAPI
144    # ./bootstrap.sh
145    # rpm --eval "%configure" | sh
146    # make
147    # make install
148
149
150 ##
151 # libhbalinux
152 ##############
153
154 DEPENDENCIES
155
156 * HBA API Wrapper
157
158 * autoconf
159 * autotools
160 * sysconftool
161 * automake
162 * libtool
163 * libpciaccess-devel
164
165 PROCESS
166
167 1) Obtain the latest source
168
169    git clone git://open-fcoe.org/libhbalinux.git
170
171 2) Bootstrap, configure, make and make install
172    # cd libhbalinux
173    # ./bootstrap.sh
174    # rpm --eval "%configure" | sh
175    # make
176    # make install
177
178
179 ##
180 # fcoe-utils
181 ############
182
183 DEPENDENCIES
184
185 * libnl (see DCB section)
186 * libhbalinux
187 * lldpad v0.9.26 or greater (optional configure flag to build without)
188
189 * autoconf
190 * autotools
191 * sysconftool
192 * automake
193 * libtool
194
195 PROCESS
196
197 1) Obtain the latest source
198
199    git clone git://open-fcoe.org/fcoe-utils.git
200
201 2) Bootstrap, configure, make and make install
202    # cd fcoe-utils
203    # ./bootstrap.sh
204    Either execute the next line for System V init script install
205    # rpm --eval "%configure" | sh
206    or the following line to install systemd unit scripts
207    # rpm --eval "%configure --with-systemdsystemunitdir=/" | sh
208    # make
209    # make install
210
211 ##
212 # Example Configuration
213 #######################
214
215 This example configures interface eth3 to automatically connect to storage over
216 a discovered VLAN.
217
218 1) Configure FCoE on the interface
219    # cd /etc/fcoe/
220    # cp cfg-ethx cfg-eth3
221
222 2) Start lldpad and configure the interface for DCB.
223    # service lldpad start
224    # dcbtool sc eth3 dcb on
225    # dcbtool sc eth3 pfc e:1
226    # dcbtool sc eth3 app:fcoe e:1
227
228    As a convenience there is a script that will confirm if DCB has been
229    configured correctly for FCoE. The script is run as follows,
230
231    <fcoe-utils source>/debug/dcbcheck.sh eth3
232    (note: this is on the root device, not the VLAN)
233
234    Follow the suggestions and repeatedly run the script until it states that
235    DCB is configured correctly.
236
237 3) Start fcoe
238    # service fcoe start
239      After a few moments your storage should appear (assuming everything is
240      configured correctly on the fabric)
241
242 4) Setup lldpad and fcoe to start when booting
243     # chkconfig lldpad on
244     # chkconfig fcoe on
245
246
247 ##
248 # Reporting Errors
249 ##################
250
251 Most steps cannot be skipped. Resolve issues before moving forward.
252
253 Please run '<fcoe-utils-src>/debug/fcoedump.sh eth3.<VID>-fcoe &>dump.out'
254 and provide the dump.out file with the bug report. Defects can be filed
255 against the distribution used, reported to the Ethernet vendor of the
256 card in use, or mailed to fcoe-devel@open-fcoe.org.
257
258
259 ##
260 # Debugging Tools
261 ###################
262
263 1) Discover VLANs manually
264    # fipvlan -a
265    Fibre Channel Forwarders Discovered
266    interface | VLAN | FCF MAC
267    ------------------------------------
268    eth3      | 101  | 00:0d:ec:a3:3a:80
269
270    VLANs should be automatically discovered by the FCoE start up process which
271    adds a VLAN to the real device. The VLAN can be identified by the name
272    ethx.vid-fcoe.
273
274 2) fcping can be used to ping targets to verify connectivity.
275
276    # fcping -h eth3.<VID>-fcoe  -F E10AEF -c 3
277      sending echo to 0xE10AEF
278      echo    1 REJECT received                 0.116 ms
279      echo    2 REJECT received                 0.222 ms
280      echo    3 REJECT received                 0.226 ms
281      3 frames sent, 3 received 3 errors, 0.000% loss, avg. rt time 0.188 ms