README.md

   1 [![basic-build-and-ci](https://github.com/openSUSE/multipath-tools/actions/workflows/build-and-unittest.yaml/badge.svg)](https://github.com/openSUSE/multipath-tools/actions/workflows/build-and-unittest.yaml) [![compile and unit test on native arch](https://github.com/openSUSE/multipath-tools/actions/workflows/native.yaml/badge.svg)](https://github.com/openSUSE/multipath-tools/actions/workflows/native.yaml) [![compile and unit test on foreign arch](https://github.com/openSUSE/multipath-tools/actions/workflows/foreign.yaml/badge.svg)](https://github.com/openSUSE/multipath-tools/actions/workflows/foreign.yaml)
   2
   3 multipath-tools for Linux
   4 =========================
   5
   6
   7 https://github.com/opensvc/multipath-tools
   8
   9 This package provides the following binaries to drive the Device Mapper multipathing driver:
  10
  11 * multipath - Device mapper target autoconfig.
  12 * multipathd - Multipath daemon.
  13 * mpathpersist - Manages SCSI persistent reservations on dm multipath devices.
  14 * kpartx - Create device maps from partition tables.
  15
  16
  17 Releases
  18 ========
  19
  20 To get a specific X.Y.Z release, use one of the following method:
  21
  22
  23 Git
  24 ---
  25
  26     git clone https://github.com/opensvc/multipath-tools.git
  27     cd multipath-tools
  28     git tag
  29     git archive --format=tar.gz --prefix=multipath-tools-X.Y.Z/ X.Y.Z > ../multipath-tools-X.Y.Z.tar.gz
  30
  31
  32 Direct download
  33 ---------------
  34
  35     wget "https://github.com/opensvc/multipath-tools/archive/X.Y.Z.tar.gz" -O multipath-tools-X.Y.Z.tar.gz
  36
  37
  38 Browser
  39 -------
  40
  41 Go to: https://github.com/opensvc/multipath-tools/tags
  42 Select a release-tag and then click on "zip" or "tar.gz".
  43
  44
  45 Source code
  46 ===========
  47
  48 To get latest devel code:
  49
  50     git clone https://github.com/opensvc/multipath-tools.git
  51
  52 Github page: https://github.com/opensvc/multipath-tools
  53
  54
  55 Building multipath-tools
  56 ========================
  57
  58 Prerequisites: development packages of for `libdevmapper`, `libreadline`,
  59 `libaio`, `libudev`, `libjson-c`, `liburcu`, and `libsystemd`.
  60
  61 To build multipath-tools, type:
  62
  63     make
  64         make DESTDIR="/my/target/dir" install
  65
  66 To uninstall, type:
  67
  68     make uninstall
  69
  70 Customizing the build
  71 ---------------------
  72
  73 The following variables can be passed to the `make` command line:
  74
  75  * `ENABLE_LIBDMMP=0`: disable building libdmmp
  76  * `ENABLE_DMEVENTS_POLL=0`: disable support for the device-mapper event
  77    polling API. For use with pre-5.0 kernels that don't supprt dmevent polling
  78    (but even if you don't use this option, multipath-tools will work with
  79    these kernels).
  80  * `SCSI_DH_MODULES_PRELOAD="(list)"`: specify a space-separated list of SCSI
  81    device handler kernel modules to load early during boot. Some
  82    multipath-tools functionality depends on these modules being loaded
  83    early. This option causes a *modules-load.d(5)* configuration file to be
  84    created, thus it depends on functionality provided by *systemd*.
  85    This variable only matters for `make install`.
  86
  87 Note: The usefulness of the preload list depends on the kernel configuration.
  88 It's especially useful if `scsi_mod` is builtin but `scsi_dh_alua` and
  89 other device handler modules are built as modules. If `scsi_mod` itself is compiled
  90 as a module, it might make more sense to use a module softdep for the same
  91 purpose.
  92
  93 See `Makefile.inc` for additional variables to customize paths and compiler
  94 flags.
  95
  96 Special Makefile targets
  97 ------------------------
  98
  99 The following targets are intended for developers only.
 100
 101  * `make test` to build and run the unit tests
 102  * `make valgrind-test` to run the unit tests under valgrind
 103  * `make abi` to create an XML representation of the ABI of the libraries in
 104    the `abi/` subdirectory
 105  * `make abi-test` to compare the ABI of a different multipath-tools version,
 106    which must be stored in the `reference-abi/` subdirectory. If this test
 107    fails, the ABI has changed wrt the reference.
 108  * `make compile-commands.json` to create input for [clangd](https://clangd.llvm.org/).
 109
 110
 111 Add storage devices
 112 ===================
 113
 114 Follow the instructions in the `libmultipath/hwtable.c` header.
 115
 116
 117 Mailing list
 118 ============
 119
 120 (subscribers-only)
 121 To subscribe and archives: https://www.redhat.com/mailman/listinfo/dm-devel
 122 Searchable: https://marc.info/?l=dm-devel
 123
 124
 125 Changelog
 126 =========
 127
 128 pre-0.4.5: https://web.archive.org/web/20070309224034/http://christophe.varoqui.free.fr/wiki/wakka.php?wiki=ChangeLog
 129 post-0.4.5: https://github.com/opensvc/multipath-tools/commits/master
 130
 131
 132 Maintainer
 133 ==========
 134
 135 Christophe Varoqui <christophe.varoqui@opensvc.com>
 136 Device-mapper development mailing list <dm-devel@redhat.com>
 137
 138
 139 Licence
 140 =======
 141
 142 The multipath-tools source code is covered by several different licences.
 143 Refer to the individual source files for details.
 144 Source files which do not specify a licence are shipped under LGPL-2.0
 145 (see `LICENSES/LGPL-2.0`).
 146