tgt 1:1.0.51-1 / usr / share / doc / tgt / README.sheepdog

Sheepdog is a distributed storage system for QEMU, iSCSI clients and
RESTful services. It provides highly available block level storage
volumes that can be attached to QEMU-based virtual machines. The
volumes can also be attached to other virtual machines and operating
systems run on baremetal hardware if they support iSCSI
protocol. Sheepdog scales to several hundreds nodes, and supports
advanced volume management features such as snapshot, cloning, and
thin provisioning. Stuff like volumes, snapshots, QEMU's vm-state
(from live snapshot), even ISO files can be stored in the Sheepdog
cluster.

With tgt, sheepdog's virtual disks can be used by iSCSI
initiators. Below is a brief description of setup.

1. Install and launch tgt

$ git clone https://github.com/fujita/tgt.git
$ cd tgt
$ make
# make install
2. Create a sheepdog VDI

There is no special procedures in this step.

$ dog vdi create tgt0 100G
Of course you can use existing VDIs as iSCSI logical units.

3. Setup iSCSI target provided by tgt

One logical unit corresponds to one VDI of sheepdog. In this step, we
create iSCSI target and logical unit which can be seen by iSCSI
initiator.

# tgtd
# tgtadm --op new --mode target --tid 1 --lld iscsi --targetname iqn.2013-10.org.sheepdog-project
# tgtadm --op new --mode lu --tid 1 --lun 2 --bstype sheepdog --backing-store unix:/sheep_store/sock:tgt0
# tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL

The most important parameter is --backing-store which is required by
tgtadm when we create the logical unit in the target (the third line
of the above commands). With this parameter, we tell the tgtd
process how to connect to the sheep process, which VDI we use as the
logical unit, which snapshot ID of the VDI we use. The form of the
--backing-store option is like this:

 unix:path_of_unix_domain_socket:vdi
 unix:path_of_unix_domain_socket:vdi:tag
 unix:path_of_unix_domain_socket:vdi:snapid
 tcp:host:port:vdi
 tcp:host:port:vdi:tag
 tcp:host:port:vdi:snapid

We use a special case of the first one in the above command
sequence. It means "connect to sheep process via unix domain socket
protocol, path of unix domain socket is /sheep_store/sock, use VDI
named tgt0 as a backing store of newly created logical unit".

You can also specify sheep which is running on remote host via
TCP. But if tgtd process is running on a same host of sheep process,
there is no benefit of using TCP. Unix domain socket can provide
faster connection than TCP.

You can also specify tag or ID of snapshots via suffix of the
--backing-store option.

4. Setup iSCSI session (example of the open-iscsi initiator on Linux)

After setting up iSCSI target, you can use the VDIs from any virtual
machines and operating systems which supports iSCSI initiator. Many of
popular hypervisors and operating systems support it (e.g. VMware ESX
Family, Linux, Windows, etc). In this example, the way of Linux +
open-iscsi is described.

At first, you have to install open-iscsi ( http://www.open-iscsi.org/
) and launch it. Major linux distros provide their open-iscsi
package. Below is a way of installation in Debian and Ubuntu based
systems.

# apt-get install open-iscsi
# /etc/init.d/open-iscsi start

Next, we need to let iscsid discover and login to the target we've
already created in the above sequence. If the initiator is running
on different host from the target, you have to change the IP
addresses in the below commands.

# iscsiadm -m discovery -t st -p 127.0.0.1
# iscsiadm -m node --targetname iqn.2013-10.org.sheepdog-project --portal 127.0.0.1:3260 --login

New device files, e.g. /dev/sdb, will be created on your system after
login completion. Now your system can use the speepdog VDIs like
ordinal HDDs.

ToDo

Currently, iSCSI multipath is not supported by sheepdog. It will be
implemented in v0.9.0.

The latest version of this guide can be found here:
https://github.com/sheepdog/sheepdog/wiki/General-protocol-support-%28iSCSI-and-NBD%29