extras/multipath/README

   1 Dependancies :
   2 ==============
   3
   4 o libdevmapper : comes with device-mapper-XXXX.tar.gz
   5   See www.sistina.com
   6   This lib has been dropped in the multipath tree
   7 o libsysfs : comes with sysutils or udev
   8   See ftp.kernel.org/pub/linux/utils/kernel/hotplug/
   9 o Linux kernel 2.6.0 with udm5 patchset
  10   http://people.sistina.com/~thornber/dm/
  11 o udev
  12   See ftp.kernel.org/pub/linux/utils/kernel/hotplug/
  13
  14 How it works :
  15 ==============
  16
  17 Fill the all_paths array. Each path store this info :
  18
  19 struct path {
  20         char dev[FILE_NAME_SIZE];
  21         char sg_dev[FILE_NAME_SIZE];
  22         struct scsi_idlun scsi_id;
  23         struct sg_id sg_id;
  24         int state;
  25         char wwid[WWID_SIZE];
  26 };
  27
  28 scsi_id, sg_dev and sg_id are only really useful for 2.4
  29 kernels, for which SG cmnds must go through sg devs.
  30 In 2.5+ we have the nice opportunity to send SG cmnds
  31 through SCSI bdevs.
  32
  33 For 2.4 compat, we pivot on idlun tupple to map sg devs
  34 to SCSI bdevs.
  35
  36 2.4 does not do device enumeration, so we must scan a
  37 defined number of sg devs and scsi bdevs. Good enough.
  38 In 2.5+, we rely on libsysfs (sysutils) to access to
  39 sysfs device enums.
  40
  41 the wwid is retrieved by a switch fonction. Only White
  42 Listed HW can filled this field. For now every FC array
  43 HW listed in kernel's devinfo.c is White Listed, assuming
  44 the WWID is stored is the SCSI-3 standard 0x83 EVPD page.
  45
  46 When all_paths is filled, we coalesce the paths and store
  47 the result in mp array. Each mp is a struct like this :
  48
  49 struct multipath {
  50         char wwid[WWID_SIZE];
  51         int npaths;
  52         int pindex[MAX_MP_PATHS];
  53 };
  54
  55 When mp is filled, the device maps are fed to the kernel
  56 through libdevmapper.
  57
  58 The naming of the corresponding block device is handeld
  59 by udev with the help of the devmap_name proggy. It is
  60 called by the following rule in /etc/udev/udev.rules :
  61 KERNEL="dm-[0-9]*", PROGRAM="/sbin/devmap_name %M %m", \
  62 NAME="%k", SYMLINK="%c"
  63
  64 Notes :
  65 =======
  66
  67 o On 2.4, make sure you have enough /dev/sg* nodes
  68   (/dev/MAKEDEV if necesary). Same goes for /dev/sd*
  69
  70 o path coalescing relies on a path unique id being found.
  71   This unique id, lacking a standard method, is vendor
  72   specific. A switch function (get_unique_id) is present
  73   and an example function is provided for storageworks
  74   arrays (get_evpd_wwid). Feel free to enrich
  75   with hardware you have at hand :)
  76
  77 o The kernel does NOT manage properly ghosts paths
  78   with StorageWorks HW. Seems nobody cares after a load
  79   of posts to linux-scsi.
  80
  81 o 2.4.21 version of DM does not like even segment size.
  82   if you enconter pbs with this, upgrade DM.
  83
  84 Credits :
  85 =========
  86
  87 o Heavy cut'n paste from sg_utils. Thanks goes to D.
  88   Gilbert.
  89 o Light cut'n paste from dmsetup. Thanks Joe Thornber.
  90 o Greg KH for the nice sysfs API.