Goock is a Golang library/client for discovering and managing block device. it dramatically eases the efforts needed when connecting/disconnecting to storage backend.

• Overview
• Features
• Installation
• Requirements
• Usage
  • As a library
    • Connect to a storage device
    • Disconnect a device from storage system
  • As a client
    • Show the goock version
    • Connect to a LUN on specific target
    • Connect and rescan all LUNs from a target
    • Disconnect a device from remote system
    • Extend a connected device
    • Get command help
• Testing
  • Unit test
  • Manual test
• Contributions
• License
• FAQ

Goock aims at providing a easy-to-use library/client for block device discovering and management. user no longer needs the use of multiple linux tools like open-iscsi, multipath-tools, sysfsutils and sg3-utils). Instead,
goock will leverage the power of many *nux device management tools, and provides simple and straightforward API/CLI for developers and administrators.

This project is inspired by OpenStack project os-brick

• Discovery of devices for iSCSI transport protocol.
• Discovery of devices for FibreChanel transport protocol.
• Removal of devices from a host
• Multipath support

Note: if you want build binary from source, please firstly setup Go environment.

• Get the binary of goock, you have 2 ways to do this:

  • Download the binary of goock from goock releases

  • Either:

    • download the source and it's dependencies from github

    go get -d -v -t github.com/peter-wangxu/goock
    

    • Build the binary

    go build

    a binary file named goock will be in place for use.

• Install tools

This step installs couple of tools that goock relies on.

On Debian/Ubuntu

sudo apt-get install open-iscsi multipath-tools sysfsutils sg3-utils

On RHEL/CentOS

yum install iscsi-initiator-utils device-mapper-multipath sysfsutils sg3_utils

Goock can be built or developed on both Linux or Windows platform.

• Linux/Windows
• Go 1.7 or later

Goock is a library for connecting/disconnecting block devices for any Golang based software. the example usage below:

package main

import (
        "github.com/peter-wangxu/goock/connector"
)

iscsi := connector.New()

conn := connector.ConnectionProperty{}
conn.TargetPortals = []string{"192.168.1.30"}
conn.TargetIqns = []string{"iqn.xxxxxxxxxxxxxx"}
conn.TargetPortals = []int{10}

deviceInfo, _ : = iscsi.ConnectVolume(conn)

package main

import (
        "github.com/peter-wangxu/goock/connector"
)

iscsi := connector.New()

conn := connector.ConnectionProperty{}
conn.TargetPortals = []string{"192.168.1.30"}
conn.TargetIqns = []string{"iqn.xxxxxxxxxxxxxx"}
conn.TargetPortals = []int{10}

deviceInfo, _ : = iscsi.DisconnectVolume(conn)

Sometimes, the device needs be extended on the storage system, while host was not aware of size change immediately, in this case, a host side rescan is needed.

package main

import (
        "github.com/peter-wangxu/goock/connector"
)

iscsi := connector.New()

conn := connector.ConnectionProperty{}
conn.TargetPortals = []string{"192.168.1.30"}
conn.TargetIqns = []string{"iqn.xxxxxxxxxxxxxx"}
conn.TargetPortals = []int{10}

deviceInfo, _ : = iscsi.ExtendVolume(conn)

Goock is also client tool, which can be used from shell. When the host is connecting with backend storage(such as enterprise array, DellEMC Unity, HPE 3Par etc.), goock can be helpful to connect with the storage device and inspect its information.

NOTE: make sure you have permission to operate the block device.

Example usage below:

goock -v

goock info

the output likes below:

Volume Information:
iSCSI Qualified Name(IQN)      :
iqn.1993-08.org.debian:01:b974ee37fea
Host Bus Adapter               :
[20000090fa534cd0:10000090fa534cd0 20000090fa534cd1:10000090fa534cd1]
Connected Fibre Channel Target :
[5006016089200925:5006016d09200925 50060160b6e00e5a:5006016036e00e5a 5006016089200925:5006016509200925 50060160b6e00e5a:5006016136e00e5a]
Connected iSCSI sessions       :
192.168.1.99 192.168.1.100

# Connect and rescan storage device whose iSCSI target ip is <target IP>, the desired
# Device LUN ID is [LUN ID]
goock connect <TARGET> <LUN ID>

The <TARGET> here and below commands example denotes the IP address or WWN of remote storage device.

The <LUN ID> is allocated by the storage array, usually a integer less than 255.

Not support yet.

goock connect <TARGET>

goock disconnect <Target> <LUN ID>

goock extend <Target> <LUN ID>

or

Not support yet.

goock extend /dev/sdx

goock help connect

cd goock
go test -v ./...

• first build a binary from source

cd goock
go build

• run goock command by specifying some parameters

goock connect <TARGET> <LUN ID>

Simply fork this repo and send PR for your code change(also tests to cover your change), remember to give a title and description of your PR.

Apache License Version 2.0