goiscsi

package module
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 26, 2024 License: Apache-2.0 Imports: 12 Imported by: 6

README

goiscsi

A portable Go module for iscsi related operations such as discovery and login

Features

The following features are supported:

  • Discover iSCSI targets provided by a specific portal, optionally log into each target
  • Discover the iSCSI Initiators defined on the local system
  • Log into a specific portal/target
  • Log out of a specific portal/target
  • Rescan all connected iSCSI sessions

Implementation options

Two implementations of the goiscsi.ISCSIinterface exist; one is for Linux based systems and one is a mock implementation. When instantiating an implementation of the goiscsi.ISCSIinterface interface, the factories accept a map[string]string option that allows the user to set specific key/values within the implementation.

The goiscsi.ISCSIinterface is defined as:

type ISCSIinterface interface {
	// Discover the targets exposed via a given portal
	// returns an array of ISCSITarget instances
	DiscoverTargets(address string, login bool) ([]ISCSITarget, error)

	// Get a list of iSCSI initiators defined in a specified file
	// To use the system default file of "/etc/iscsi/initiatorname.iscsi", provide a filename of ""
	GetInitiators(filename string) ([]string, error)

	// Log into a specified target
	PerformLogin(target ISCSITarget) error

	// Log out of a specified target
	PerformLogout(target ISCSITarget) error

	// Rescan current iSCSI sessions
	PerformRescan() error

	// generic implementations
	isMock() bool
	getOptions() map[string]string
}

Many operations deal with iSCSI Targets via a type of goiscsi.ISCSITarget, defined as:

type ISCSITarget struct {
	Portal   string
	GroupTag string
	Target   string
}
LinuxISCSI

When instantiating a Linux implementation via goiscsi.NewLinuxISCSI the following options are available

Key Meaning
chrootDirectory Run iscsiadm in a chrooted environment with the root set to this value.
Default is to not chroot
MockISCSI

When instantiating a mock implementation via goiscsi.NewMockISCSI, the follwoing options are available:

Key Meaning
numberOfInitiators Defines the number of initiators that will be returned via the GetInitiators method.
Default is "1"
numberOfTargets Defines the number of targets that will be returned via the DiscoverTargets method.
Default is "1"

Usage examples

The following example will instantiate a Linux based iSCSI client and Discover the targets exposed via the portal at address

import (
    "errors"
    
    "github.com/dell/goiscsi"
)

func printTargets(address string) {
    var c goiscsi.ISCSIinterface
    c := goiscsi.NewLinuxISCSI(map[string]string{})
    targets, err := c.DiscoverTargets(address, false)
    if err != nil {
        return
    }
    for _, t := range targets {
        fmt.Printf("Found target: %s", tgt.Target)
    }
}

The following example will instantiate a Mock iSCSI client, set the number of targets to 3, and Discover the mocked targets

import (
    "errors"
    
    "github.com/dell/goiscsi"
)

func printTargets(address string) {
    var c goiscsi.ISCSIinterface
    opts := make(map[string]string, 0)
    opts[goiscsi.MockNumberOfTargets] = "3"
    c := goiscsi.NewMockISCSI(opts)
    targets, err := c.DiscoverTargets(address, false)
    if err != nil {
        return
    }
    for _, t := range targets {
        fmt.Printf("Found target: %s", tgt.Target)
    }
}

Documentation

Index

Constants

View Source 
const (
	// ChrootDirectory allows the iscsiadm commands to be run within a chrooted path, helpful for containerized services
	ChrootDirectory = "chrootDirectory"
	// DefaultInitiatorNameFile is the default file which contains the initiator names
	DefaultInitiatorNameFile = "/etc/iscsi/initiatorname.iscsi"

	// Timeout for iscsiadm command to execute
	Timeout = 30
)
View Source 
const (
	// MockNumberOfInitiators controls the number of initiators found in mock mode
	MockNumberOfInitiators = "numberOfInitiators"
	// MockNumberOfTargets controls the number of targets found in mock mode
	MockNumberOfTargets = "numberOfTargets"
	// MockNumberOfSessions controls the number of  iSCIS sessions found in mock mode
	MockNumberOfSessions = "numberOfSession"
	// MockNumberOfNodes controls the number of  iSCIS sessions found in mock mode
	MockNumberOfNodes = "numberOfNode"
)
View Source 
const (
	ISCSISessionStateLOGGEDIN ISCSISessionState = "LOGGED_IN"
	ISCSISessionStateFAILED   ISCSISessionState = "FAILED"
	ISCSISessionStateFREE     ISCSISessionState = "FREE"

	ISCSIConnectionStateFREE            ISCSIConnectionState = "FREE"
	ISCSIConnectionStateTRANSPORTWAIT   ISCSIConnectionState = "TRANSPORT WAIT"
	ISCSIConnectionStateINLOGIN         ISCSIConnectionState = "IN LOGIN"
	ISCSIConnectionStateLOGGEDIN        ISCSIConnectionState = "LOGGED IN"
	ISCSIConnectionStateINLOGOUT        ISCSIConnectionState = "IN LOGOUT"
	ISCSIConnectionStateLOGOUTREQUESTED ISCSIConnectionState = "LOGOUT REQUESTED"
	ISCSIConnectionStateCLEANUPWAIT     ISCSIConnectionState = "CLEANUP WAIT"

	ISCSITransportNameTCP  ISCSITransportName = "tcp"
	ISCSITransportNameISER ISCSITransportName = "iser"
)

ISCSI session and connection states

Variables

View Source 
var (
	// ErrIscsiNotInstalled is returned when the iscsi utilities are not
	// found on a system
	ErrIscsiNotInstalled = errors.New("iSCSI utilities are not installed")
	// ErrNotImplemented is returned when a platform does not implement
	ErrNotImplemented = errors.New("not implemented")
)
View Source 
var GOISCSIMock struct {
	InduceDiscoveryError          bool
	InduceInitiatorError          bool
	InduceLoginError              bool
	InduceLogoutError             bool
	InduceRescanError             bool
	InduceGetSessionsError        bool
	InduceGetNodesError           bool
	InduceCreateOrUpdateNodeError bool
	InduceDeleteNodeError         bool
	InduceSetCHAPError            bool
}

GOISCSIMock is a struct controlling induced errors

Functions

This section is empty.

Types

type ISCSIConnectionState added in v1.1.0 

type ISCSIConnectionState string

ISCSIConnectionState holds iscsi connection state

type ISCSINode added in v1.1.0 

type ISCSINode struct {
	Target string
	Portal string
	Fields map[string]string
}

ISCSINode defines an iSCSI node info

type ISCSISession added in v1.1.0 

type ISCSISession struct {
	Target               string
	Portal               string
	SID                  string
	IfaceTransport       ISCSITransportName
	IfaceInitiatorname   string
	IfaceIPaddress       string
	ISCSISessionState    ISCSISessionState
	ISCSIConnectionState ISCSIConnectionState
	Username             string
	Password             string
	UsernameIn           string
	PasswordIn           string
}

ISCSISession defines an iSCSI session info

type ISCSISessionState added in v1.1.0 

type ISCSISessionState string

ISCSISessionState holds iscsi session state

type ISCSITarget 

type ISCSITarget struct {
	Portal   string
	GroupTag string
	Target   string
}

ISCSITarget defines an iSCSI target

type ISCSITransportName added in v1.1.0 

type ISCSITransportName string

ISCSITransportName holds iscsi transport name

type ISCSIType 

type ISCSIType struct {
	// contains filtered or unexported fields
}

ISCSIType is the base structre for each platform implementation

type ISCSIinterface 

type ISCSIinterface interface {
	// Discover the targets exposed via a given portal
	// returns an array of ISCSITarget instances
	DiscoverTargets(address string, login bool) ([]ISCSITarget, error)

	// Get a list of iSCSI initiators defined in a specified file
	// To use the system default file of "/etc/iscsi/initiatorname.iscsi", provide a filename of ""
	GetInitiators(filename string) ([]string, error)

	// Log into a specified target
	PerformLogin(target ISCSITarget) error

	// Log out of a specified target
	PerformLogout(target ISCSITarget) error

	// Rescan current iSCSI sessions
	PerformRescan() error

	// Query information about sessions
	GetSessions() ([]ISCSISession, error)

	// Query information about nodes
	GetNodes() ([]ISCSINode, error)

	// Set CHAP credentials for a target (creates/updates node database)
	SetCHAPCredentials(target ISCSITarget, username, password string) error

	// CreateOrUpdateNode creates new or update existing iSCSI node in iscsid database
	CreateOrUpdateNode(target ISCSITarget, options map[string]string) error

	// DeleteNode delete iSCSI node from iscsid database
	DeleteNode(target ISCSITarget) error
	// contains filtered or unexported methods
}

ISCSIinterface is the interface that provides the iSCSI client functionality

type LinuxISCSI 

type LinuxISCSI struct {
	ISCSIType
	// contains filtered or unexported fields
}

LinuxISCSI provides many iSCSI-specific functions.

func NewLinuxISCSI 

func NewLinuxISCSI(opts map[string]string) *LinuxISCSI

NewLinuxISCSI returns an LinuxISCSI client

func (*LinuxISCSI) CreateOrUpdateNode added in v1.1.0 

func (iscsi *LinuxISCSI) CreateOrUpdateNode(target ISCSITarget, options map[string]string) error

CreateOrUpdateNode creates new or update existing iSCSI node in iscsid dm

func (*LinuxISCSI) DeleteNode added in v1.1.0 

func (iscsi *LinuxISCSI) DeleteNode(target ISCSITarget) error

DeleteNode delete iSCSI node from iscsid database

func (*LinuxISCSI) DiscoverTargets 

func (iscsi *LinuxISCSI) DiscoverTargets(address string, login bool) ([]ISCSITarget, error)

DiscoverTargets runs an iSCSI discovery and returns a list of targets.

func (*LinuxISCSI) GetInitiators 

func (iscsi *LinuxISCSI) GetInitiators(filename string) ([]string, error)

GetInitiators returns a list of initiators on the local system.

func (*LinuxISCSI) GetNodes added in v1.1.0 

func (iscsi *LinuxISCSI) GetNodes() ([]ISCSINode, error)

GetNodes will query information about nodes

func (*LinuxISCSI) GetSessions added in v1.1.0 

func (iscsi *LinuxISCSI) GetSessions() ([]ISCSISession, error)

GetSessions will query information about sessions

func (*LinuxISCSI) PerformLogin 

func (iscsi *LinuxISCSI) PerformLogin(target ISCSITarget) error

PerformLogin will attempt to log into an iSCSI target

func (*LinuxISCSI) PerformLogout 

func (iscsi *LinuxISCSI) PerformLogout(target ISCSITarget) error

PerformLogout will attempt to log out of an iSCSI target

func (*LinuxISCSI) PerformRescan 

func (iscsi *LinuxISCSI) PerformRescan() error

PerformRescan will rescan targets known to current sessions

func (*LinuxISCSI) SetCHAPCredentials added in v1.2.0 

func (iscsi *LinuxISCSI) SetCHAPCredentials(target ISCSITarget, username, password string) error

SetCHAPCredentials will set CHAP credentials

type MockISCSI 

type MockISCSI struct {
	ISCSIType
}

MockISCSI provides a mock implementation of an iscsi client

func NewMockISCSI 

func NewMockISCSI(opts map[string]string) *MockISCSI

NewMockISCSI returns an mock ISCSI client

func (*MockISCSI) CreateOrUpdateNode added in v1.1.0 

func (iscsi *MockISCSI) CreateOrUpdateNode(target ISCSITarget, options map[string]string) error

CreateOrUpdateNode creates new or update existing iSCSI node in iscsid database

func (*MockISCSI) DeleteNode added in v1.1.0 

func (iscsi *MockISCSI) DeleteNode(target ISCSITarget) error

DeleteNode delete iSCSI node from iscsid database

func (*MockISCSI) DiscoverTargets 

func (iscsi *MockISCSI) DiscoverTargets(address string, login bool) ([]ISCSITarget, error)

DiscoverTargets runs an iSCSI discovery and returns a list of targets.

func (*MockISCSI) GetInitiators 

func (iscsi *MockISCSI) GetInitiators(filename string) ([]string, error)

GetInitiators returns a list of initiators on the local system.

func (*MockISCSI) GetNodes added in v1.1.0 

func (iscsi *MockISCSI) GetNodes() ([]ISCSINode, error)

GetNodes will query iSCSI session info

func (*MockISCSI) GetSessions added in v1.1.0 

func (iscsi *MockISCSI) GetSessions() ([]ISCSISession, error)

GetSessions will query iSCSI session info

func (*MockISCSI) PerformLogin 

func (iscsi *MockISCSI) PerformLogin(target ISCSITarget) error

PerformLogin will attempt to log into an iSCSI target

func (*MockISCSI) PerformLogout 

func (iscsi *MockISCSI) PerformLogout(target ISCSITarget) error

PerformLogout will attempt to log out of an iSCSI target

func (*MockISCSI) PerformRescan 

func (iscsi *MockISCSI) PerformRescan() error

PerformRescan will will rescan targets known to current sessions

func (*MockISCSI) SetCHAPCredentials added in v1.2.0 

func (iscsi *MockISCSI) SetCHAPCredentials(target ISCSITarget, username, password string) error

SetCHAPCredentials will set CHAP credentials

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.