VBLADE/vblade-master/README

   1
   2 INTRODUCTION
   3 ------------
   4
   5 The vblade is a minimal ATA over Ethernet (AoE) storage target.  Its
   6 focus is simplicity, not performance or richness of features.  It
   7 exports a seekable file available over an ethernet local area network
   8 (LAN) via the AoE data storage protocol.
   9
  10 The name, "vblade," is historical: It is a virtual EtherDrive (R)
  11 blade.  The first AoE target hardware sold by Coraid was in a blade
  12 form factor, ten to a 4-rack-unit chassis.
  13
  14 The seekable file is typically a block device like /dev/md0 but even
  15 regular files will work.  Sparse files can be especially convenient.
  16 When vblade exports the block storage over AoE it becomes a storage
  17 target.  Another host on the same LAN can access the storage if it has
  18 a compatible aoe kernel driver.
  19
  20 BUILDING
  21 --------
  22
  23 The following command should build the vblade program on a Linux-based
  24 system:
  25
  26   make
  27
  28 For FreeBSD systems, include an extra parameter like so:
  29
  30   make PLATFORM=freebsd
  31
  32 EXAMPLES
  33 --------
  34
  35 There is a "vbladed" script that daemonizes the program and sends its
  36 output to the logger program.  Make sure you have logger installed if
  37 you would like to run vblade as a daemon with the vbladed script.
  38
  39   ecashin@kokone vblade$ echo 'I have logger' | logger
  40   ecashin@kokone vblade$ tail -3 /var/log/messages
  41   Feb  8 14:52:49 kokone -- MARK --
  42   Feb  8 15:12:49 kokone -- MARK --
  43   Feb  8 15:19:56 kokone logger: I have logger
  44
  45 Here is a short example showing how to export a block device with a
  46 vblade.  (This is a loop device backed by a sparse file, but you could
  47 use any seekable file instead of /dev/loop7.)
  48
  49   ecashin@kokone vblade$ make
  50   cc -Wall   -c -o aoe.o aoe.c
  51   cc -Wall   -c -o linux.o linux.c
  52   cc -Wall   -c -o ata.o ata.c
  53   cc -o vblade aoe.o linux.o ata.o
  54   ecashin@kokone vblade$ su
  55   Password:
  56   root@kokone vblade# modprobe loop
  57   root@kokone vblade# dd if=/dev/zero bs=1k count=1 seek=`expr 1024 \* 4096` of=bd
  58   -file
  59   1+0 records in
  60   1+0 records out
  61   1024 bytes transferred in 0.009901 seconds (103423 bytes/sec)
  62   root@kokone vblade# losetup /dev/loop7 bd-file
  63   root@kokone vblade# ./vblade 9 0 eth0 /dev/loop7
  64   ioctl returned 0
  65   4294968320 bytes
  66   pid 16967: e9.0, 8388610 sectors
  67
  68 Here's how you can use the Linux aoe driver to access the storage from
  69 another host on the LAN.
  70
  71   ecashin@kokone ecashin$ ssh makki
  72   Last login: Mon Feb  7 10:25:04 2005
  73   ecashin@makki ~$ su
  74   Password:
  75   root@makki ecashin# modprobe aoe
  76   root@makki ecashin# aoe-stat
  77       e9.0            eth1              up
  78   root@makki ecashin# mkfs -t ext3 /dev/etherd/e9.0
  79   mke2fs 1.35 (28-Feb-2004)
  80 ...
  81   Creating journal (8192 blocks): done
  82   Writing superblocks and filesystem accounting information: done
  83
  84   This filesystem will be automatically checked every 24 mounts or
  85   180 days, whichever comes first.  Use tune2fs -c or -i to override.
  86   root@makki ecashin# mkdir /mnt/e9.0
  87   root@makki ecashin# mount /dev/etherd/e9.0 /mnt/e9.0
  88   root@makki ecashin# echo hooray > /mnt/e9.0/test.txt
  89   root@makki ecashin# cat /mnt/e9.0/test.txt
  90   hooray
  91
  92 Remember: be as careful with these devices as you would with /dev/hda!
  93
  94 Jumbo Frame Compatibility
  95 -------------------------
  96
  97 Vblade can use jumbo frames provided your initiator is jumbo frame
  98 capable.  There is one small configuration gotcha to consider
  99 to avoid having the vblade kernel frequently drop frames.
 100
 101 Vblade uses a raw socket to perform AoE.  The linux kernel will
 102 only buffer a certain amount of data for a raw socket.  For 2.6
 103 kernels, this value is managed through /proc:
 104
 105 root@nai aoe# grep . /proc/sys/net/core/rmem_*
 106 /proc/sys/net/core/rmem_default:128000
 107 /proc/sys/net/core/rmem_max:128000
 108
 109 rmem_max is the max amount a user process may expand the receive
 110 buffer to -- through setsockopt(...) -- and rmem_default is, as you
 111 might expect, the default.
 112
 113 The gotcha is that this amount to buffer does not relate
 114 to the amount of user data buffered, but the amount of
 115 real data buffered.  As an example, the Intel GbE controller
 116 must be given 16KB frames to use an MTU over 8KB.
 117 For each received frame, the kernel must be able to buffer
 118 16KB, even if the aoe frame is only 60 bytes in length.
 119
 120 The linux aoe initiator will use 16 outstanding frames when
 121 used with vblade.  A good default for ensuring frames are
 122 not dropped is to allocate 16KB for 17 frames:
 123
 124 for f in /proc/sys/net/core/rmem_*; do echo $((17 * 16 * 1024)) >$f; done
 125
 126 Be sure to start vblade after changing the buffering defaults
 127 as the buffer value is set when the socket is opened.
 128
 129 AoE Initiator Compatibility
 130 ---------------------------
 131
 132 The Linux aoe driver for the 2.6 kernel is compatible if you use
 133 aoe-2.6-7 or newer.  You can use older aoe drivers but you will only
 134 be able to see one vblade per MAC address.
 135
 136 Contrib Patches
 137 ---------------
 138
 139 see contrib/README
 140
 141 Kvblade
 142 -------
 143
 144   While vblade runs as a userland process (like "ls" or "vi"), there
 145   is another program that runs inside the kernel.  It is called
 146   kvblade.  It is alpha software.