Documentation/filesystems/nfs-rdma.txt

   1 ################################################################################
   2 #                                                                              #
   3 #                               NFS/RDMA README                                #
   4 #                                                                              #
   5 ################################################################################
   6
   7  Author: NetApp and Open Grid Computing
   8  Date: May 29, 2008
   9
  10 Table of Contents
  11 ~~~~~~~~~~~~~~~~~
  12  - Overview
  13  - Getting Help
  14  - Installation
  15  - Check RDMA and NFS Setup
  16  - NFS/RDMA Setup
  17
  18 Overview
  19 ~~~~~~~~
  20
  21   This document describes how to install and setup the Linux NFS/RDMA client
  22   and server software.
  23
  24   The NFS/RDMA client was first included in Linux 2.6.24. The NFS/RDMA server
  25   was first included in the following release, Linux 2.6.25.
  26
  27   In our testing, we have obtained excellent performance results (full 10Gbit
  28   wire bandwidth at minimal client CPU) under many workloads. The code passes
  29   the full Connectathon test suite and operates over both Infiniband and iWARP
  30   RDMA adapters.
  31
  32 Getting Help
  33 ~~~~~~~~~~~~
  34
  35   If you get stuck, you can ask questions on the
  36
  37                 nfs-rdma-devel@lists.sourceforge.net
  38
  39   mailing list.
  40
  41 Installation
  42 ~~~~~~~~~~~~
  43
  44   These instructions are a step by step guide to building a machine for
  45   use with NFS/RDMA.
  46
  47   - Install an RDMA device
  48
  49     Any device supported by the drivers in drivers/infiniband/hw is acceptable.
  50
  51     Testing has been performed using several Mellanox-based IB cards, the
  52     Ammasso AMS1100 iWARP adapter, and the Chelsio cxgb3 iWARP adapter.
  53
  54   - Install a Linux distribution and tools
  55
  56     The first kernel release to contain both the NFS/RDMA client and server was
  57     Linux 2.6.25  Therefore, a distribution compatible with this and subsequent
  58     Linux kernel release should be installed.
  59
  60     The procedures described in this document have been tested with
  61     distributions from Red Hat's Fedora Project (http://fedora.redhat.com/).
  62
  63   - Install nfs-utils-1.1.2 or greater on the client
  64
  65     An NFS/RDMA mount point can be obtained by using the mount.nfs command in
  66     nfs-utils-1.1.2 or greater (nfs-utils-1.1.1 was the first nfs-utils version
  67     with support for NFS/RDMA mounts, but for various reasons we recommend using
  68     nfs-utils-1.1.2 or greater). To see which version of mount.nfs you are
  69     using, type:
  70
  71     $ /sbin/mount.nfs -V
  72
  73     If the version is less than 1.1.2 or the command does not exist,
  74     you should install the latest version of nfs-utils.
  75
  76     Download the latest package from:
  77
  78     http://www.kernel.org/pub/linux/utils/nfs
  79
  80     Uncompress the package and follow the installation instructions.
  81
  82     If you will not need the idmapper and gssd executables (you do not need
  83     these to create an NFS/RDMA enabled mount command), the installation
  84     process can be simplified by disabling these features when running
  85     configure:
  86
  87     $ ./configure --disable-gss --disable-nfsv4
  88
  89     To build nfs-utils you will need the tcp_wrappers package installed. For
  90     more information on this see the package's README and INSTALL files.
  91
  92     After building the nfs-utils package, there will be a mount.nfs binary in
  93     the utils/mount directory. This binary can be used to initiate NFS v2, v3,
  94     or v4 mounts. To initiate a v4 mount, the binary must be called mount.nfs4.
  95     The standard technique is to create a symlink called mount.nfs4 to mount.nfs.
  96
  97     This mount.nfs binary should be installed at /sbin/mount.nfs as follows:
  98
  99     $ sudo cp utils/mount/mount.nfs /sbin/mount.nfs
 100
 101     In this location, mount.nfs will be invoked automatically for NFS mounts
 102     by the system mount commmand.
 103
 104     NOTE: mount.nfs and therefore nfs-utils-1.1.2 or greater is only needed
 105     on the NFS client machine. You do not need this specific version of
 106     nfs-utils on the server. Furthermore, only the mount.nfs command from
 107     nfs-utils-1.1.2 is needed on the client.
 108
 109   - Install a Linux kernel with NFS/RDMA
 110
 111     The NFS/RDMA client and server are both included in the mainline Linux
 112     kernel version 2.6.25 and later. This and other versions of the 2.6 Linux
 113     kernel can be found at:
 114
 115     ftp://ftp.kernel.org/pub/linux/kernel/v2.6/
 116
 117     Download the sources and place them in an appropriate location.
 118
 119   - Configure the RDMA stack
 120
 121     Make sure your kernel configuration has RDMA support enabled. Under
 122     Device Drivers -> InfiniBand support, update the kernel configuration
 123     to enable InfiniBand support [NOTE: the option name is misleading. Enabling
 124     InfiniBand support is required for all RDMA devices (IB, iWARP, etc.)].
 125
 126     Enable the appropriate IB HCA support (mlx4, mthca, ehca, ipath, etc.) or
 127     iWARP adapter support (amso, cxgb3, etc.).
 128
 129     If you are using InfiniBand, be sure to enable IP-over-InfiniBand support.
 130
 131   - Configure the NFS client and server
 132
 133     Your kernel configuration must also have NFS file system support and/or
 134     NFS server support enabled. These and other NFS related configuration
 135     options can be found under File Systems -> Network File Systems.
 136
 137   - Build, install, reboot
 138
 139     The NFS/RDMA code will be enabled automatically if NFS and RDMA
 140     are turned on. The NFS/RDMA client and server are configured via the hidden
 141     SUNRPC_XPRT_RDMA config option that depends on SUNRPC and INFINIBAND. The
 142     value of SUNRPC_XPRT_RDMA will be:
 143
 144      - N if either SUNRPC or INFINIBAND are N, in this case the NFS/RDMA client
 145        and server will not be built
 146      - M if both SUNRPC and INFINIBAND are on (M or Y) and at least one is M,
 147        in this case the NFS/RDMA client and server will be built as modules
 148      - Y if both SUNRPC and INFINIBAND are Y, in this case the NFS/RDMA client
 149        and server will be built into the kernel
 150
 151     Therefore, if you have followed the steps above and turned no NFS and RDMA,
 152     the NFS/RDMA client and server will be built.
 153
 154     Build a new kernel, install it, boot it.
 155
 156 Check RDMA and NFS Setup
 157 ~~~~~~~~~~~~~~~~~~~~~~~~
 158
 159     Before configuring the NFS/RDMA software, it is a good idea to test
 160     your new kernel to ensure that the kernel is working correctly.
 161     In particular, it is a good idea to verify that the RDMA stack
 162     is functioning as expected and standard NFS over TCP/IP and/or UDP/IP
 163     is working properly.
 164
 165   - Check RDMA Setup
 166
 167     If you built the RDMA components as modules, load them at
 168     this time. For example, if you are using a Mellanox Tavor/Sinai/Arbel
 169     card:
 170
 171     $ modprobe ib_mthca
 172     $ modprobe ib_ipoib
 173
 174     If you are using InfiniBand, make sure there is a Subnet Manager (SM)
 175     running on the network. If your IB switch has an embedded SM, you can
 176     use it. Otherwise, you will need to run an SM, such as OpenSM, on one
 177     of your end nodes.
 178
 179     If an SM is running on your network, you should see the following:
 180
 181     $ cat /sys/class/infiniband/driverX/ports/1/state
 182     4: ACTIVE
 183
 184     where driverX is mthca0, ipath5, ehca3, etc.
 185
 186     To further test the InfiniBand software stack, use IPoIB (this
 187     assumes you have two IB hosts named host1 and host2):
 188
 189     host1$ ifconfig ib0 a.b.c.x
 190     host2$ ifconfig ib0 a.b.c.y
 191     host1$ ping a.b.c.y
 192     host2$ ping a.b.c.x
 193
 194     For other device types, follow the appropriate procedures.
 195
 196   - Check NFS Setup
 197
 198     For the NFS components enabled above (client and/or server),
 199     test their functionality over standard Ethernet using TCP/IP or UDP/IP.
 200
 201 NFS/RDMA Setup
 202 ~~~~~~~~~~~~~~
 203
 204   We recommend that you use two machines, one to act as the client and
 205   one to act as the server.
 206
 207   One time configuration:
 208
 209   - On the server system, configure the /etc/exports file and
 210     start the NFS/RDMA server.
 211
 212     Exports entries with the following formats have been tested:
 213
 214     /vol0   192.168.0.47(fsid=0,rw,async,insecure,no_root_squash)
 215     /vol0   192.168.0.0/255.255.255.0(fsid=0,rw,async,insecure,no_root_squash)
 216
 217     The IP address(es) is(are) the client's IPoIB address for an InfiniBand HCA or the
 218     cleint's iWARP address(es) for an RNIC.
 219
 220     NOTE: The "insecure" option must be used because the NFS/RDMA client does not
 221     use a reserved port.
 222
 223  Each time a machine boots:
 224
 225   - Load and configure the RDMA drivers
 226
 227     For InfiniBand using a Mellanox adapter:
 228
 229     $ modprobe ib_mthca
 230     $ modprobe ib_ipoib
 231     $ ifconfig ib0 a.b.c.d
 232
 233     NOTE: use unique addresses for the client and server
 234
 235   - Start the NFS server
 236
 237     If the NFS/RDMA server was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in kernel config),
 238     load the RDMA transport module:
 239
 240     $ modprobe svcrdma
 241
 242     Regardless of how the server was built (module or built-in), start the server:
 243
 244     $ /etc/init.d/nfs start
 245
 246     or
 247
 248     $ service nfs start
 249
 250     Instruct the server to listen on the RDMA transport:
 251
 252     $ echo rdma 2050 > /proc/fs/nfsd/portlist
 253
 254   - On the client system
 255
 256     If the NFS/RDMA client was built as a module (CONFIG_SUNRPC_XPRT_RDMA=m in kernel config),
 257     load the RDMA client module:
 258
 259     $ modprobe xprtrdma.ko
 260
 261     Regardless of how the client was built (module or built-in), use this command to
 262     mount the NFS/RDMA server:
 263
 264     $ mount -o rdma,port=2050 <IPoIB-server-name-or-address>:/<export> /mnt
 265
 266     To verify that the mount is using RDMA, run "cat /proc/mounts" and check the
 267     "proto" field for the given mount.
 268
 269   Congratulations! You're using NFS/RDMA!