From 6df20fafa819e9b9d014aa7c6bfdbe19fc093bba Mon Sep 17 00:00:00 2001 From: Massimiliano Cuttini Date: Mon, 23 Jul 2018 20:57:06 +0200 Subject: [PATCH] doc: rewrote the iscsi-target-cli installation Rewrote the documentation in a step-by-step style, reformatted using RST's titles instead of bolds, added installation of GIT if needed, added installation of compilers needed for tcmu-runner Signed-off-by: Massimiliano Cuttini --- doc/rbd/iscsi-target-cli-manual-install.rst | 107 ++++++++++++++++---- 1 file changed, 85 insertions(+), 22 deletions(-) diff --git a/doc/rbd/iscsi-target-cli-manual-install.rst b/doc/rbd/iscsi-target-cli-manual-install.rst index 108cdbea2fc..888540957da 100644 --- a/doc/rbd/iscsi-target-cli-manual-install.rst +++ b/doc/rbd/iscsi-target-cli-manual-install.rst @@ -4,6 +4,24 @@ Manual ceph-iscsi-cli Installation **Requirements** +to complete the installation of ceph-iscsi-cli, there are 4 different steps: + +1. Install common packages from your Linux distribution's software repository +2. Install Git to fetch the remaining packages directly from their Git repositories +3. Ensure a compatible kernel is used or install a ceph-iscsi-test client +4. Install all the components of ceph-iscsi-cli and start associated daemons: + + - tcmu-runner + - rtslib-fb + - configshell-fb + - targetcli-fb + - ceph-iscsi-config + - ceph-iscsi-cli + + +1. Install Common Packages +========================== + The following packages will be used by ceph-iscsi-cli and target tools. They must be installed from your Linux distribution's software repository on each machine that will be a iSCSI gateway: @@ -26,36 +44,68 @@ on each machine that will be a iSCSI gateway: - python flask - pyOpenSSL -**Packages** -- Linux Kernel +2. Install Git +============== - If not using a distro kernel that contains the required Ceph iSCSI patches, - then Linux kernel v4.16 or newer or the ceph-client ceph-iscsi-test - branch must be used. To get the branch run: +In order to install all the packages needed to run iSCSI with Ceph, you need to download them directly from their repository by using Git. +On CentOS/RHEL execute: - :: +:: + + > sudo yum install git + +On Debian/Ubuntu execute: + +:: + + > sudo apt install git + +To know more about Git and how it works, please, visit https://git-scm.com + + +3. Ensure a compatible kernel is used +===================================== + +Ensure you use a supported kernel that contains the required Ceph iSCSI patches: + +- all Linux distribution with a kernel v4.16 or newer, or +- Red Hat Enterprise Linux or CentOS 7.5 or later (in these distributions ceph-iscsi support is backported) +If you are already using on the compatible kernels, you can go to next step. +However, if you are NOT using a compatible kernel then ceph-client ceph-iscsi-test +branch must be used. To get the branch run: + + :: + > git clone https://github.com/ceph/ceph-client.git > git checkout ceph-iscsi-test - - .. warning:: + + .. warning:: ceph-iscsi-test is not for production use. It should only be used for proof of concept setups and testing. The kernel is only updated with Ceph iSCSI patches. General security and bug fixes from upstream are not applied. - - Check your distro's docs for specific instructions on how to build a - kernel. The only Ceph iSCSI specific requirements are the following - build options must be enabled: - - :: - + + Check your distro's docs for specific instructions on how to build a + kernel. The only Ceph iSCSI specific requirements are the following + build options must be enabled: + + :: + CONFIG_TARGET_CORE=m CONFIG_TCM_USER2=m CONFIG_ISCSI_TARGET=m -- tcmu-runner + +4. Install ceph-iscsi-cli +======================================================== + +Finally, the remaining tools can be fetched directly from their Git repositories and their associated services started + + +tcmu-runner +----------- Installation: @@ -64,7 +114,14 @@ on each machine that will be a iSCSI gateway: > git clone https://github.com/open-iscsi/tcmu-runner > cd tcmu-runner - Ceph iSCSI requires systemd so the following build command must be used: + Run the following command to install all the needed dependencies: + + :: + + > ./extra/install_dep.sh + + Now you can build the tcmu-runner. + To do so, use the following build command: :: @@ -79,7 +136,9 @@ on each machine that will be a iSCSI gateway: > systemctl enable tcmu-runner > systemctl start tcmu-runner -- rtslib-fb + +rtslib-fb +--------- Installation: @@ -89,7 +148,8 @@ on each machine that will be a iSCSI gateway: > cd rtslib-fb > python setup.py install -- configshell-fb +configshell-fb +-------------- Installation: @@ -99,7 +159,8 @@ on each machine that will be a iSCSI gateway: > cd configshell-fb > python setup.py install -- targetcli-fb +targetcli-fb +------------ Installation: @@ -115,7 +176,8 @@ on each machine that will be a iSCSI gateway: on the system. If targets have been setup and are being managed by targetcli the target service must be disabled. -- ceph-iscsi-config +ceph-iscsi-config +----------------- Installation: @@ -134,7 +196,8 @@ on each machine that will be a iSCSI gateway: > systemctl enable rbd-target-gw > systemctl start rbd-target-gw -- ceph-iscsi-cli +ceph-iscsi-cli +-------------- Installation: -- 2.39.5