iscsidsc

README

go-win-iscsidsc

Golang bindings to (some of) Windows' iSCSI Discovery Library API.

Why?

If you need to manage Windows' built-in iSCSI client from a Golang code-base, and would rather avoid having to ship separate binaries and/or Powershell scripts alongside your Go-compiled executable, this library will allow you to make calls directly to Windows' API.

How?

go-win-iscsidsc makes syscalls to Windows' API, and takes care of all the nitty-gritty details of converting back and forth from low-level structs to nice go structs.

Supported functions

We currently support the following iscsidsc.h functions:

• AddIScsiConnectionW
• AddIScsiSendTargetPortal
• GetDevicesForIScsiSessionW
• GetIScsiSessionListW
• LoginIScsiTargetW (doesn't support custom mappings)
• LogoutIScsiTarget
• RemoveIScsiSendTargetPortalW
• ReportIScsiSendTargetPortalsExW
• ReportIScsiTargetsW

If you need more functions, please feel free to open an issue, or even better a pull request!

Supported go versions

Automated builds ensure compatibility with go versions 1.11 and 1.12.

Documentation

Index

• type AuthType
• type ConnectionID
• type ConnectionInfo
• type Device
• type DigestType
• type LoginFlags
• type LoginOptions
• type Portal
• type PortalInfo
• type ScsiAddress
• type SecurityFlags
• type SessionID
• type SessionInfo
• type StorageDeviceNumber
• type WinAPICallError
  • func NewWinAPICallError(procName string, exitCode uintptr) *WinAPICallError
  • func (err *WinAPICallError) Error() string
  • func (err *WinAPICallError) ExitCode() uintptr
  • func (err *WinAPICallError) HexCode() string
  • func (err *WinAPICallError) ProcName() string

Types

type AuthType

type AuthType uint32

AuthType maps to the `ISCSI_AUTH_TYPES` C++ enum. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ne-iscsidsc-iscsi_auth_types

const (
	NoAuthAuthType AuthType = iota
	CHAPAuthType
	MutualCHAPAuthType
)

The various auth types available.

type ConnectionID

type ConnectionID struct {
	AdapterUnique   uint64
	AdapterSpecific uint64
}

ConnectionID maps to the `ISCSI_UNIQUE_CONNECTION_ID` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_unique_session_id

type ConnectionInfo

type ConnectionInfo struct {
	ConnectionID     ConnectionID
	InitiatorAddress string
	TargetAddress    string
	InitiatorSocket  uint16
	TargetSocket     uint16
	CID              [2]byte
}

ConnectionInfo maps to the `ISCSI_CONNECTION_INFOW` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_connection_infow

type Device

type Device struct {
	InitiatorName       string
	TargetName          string
	ScsiAddress         ScsiAddress
	DeviceInterfaceType uuid.UUID
	DeviceInterfaceName string
	LegacyName          string
	StorageDeviceNumber StorageDeviceNumber
	DeviceInstance      uint32
}

Device maps to the `ISCSI_DEVICE_ON_SESSIONW` C++ struct. see https://docs.microsoft.com/en-us/windows/win32/api/iscsidsc/ns-iscsidsc-iscsi_device_on_sessionw

type DigestType

type DigestType uint32

DigestType maps to the `ISCSI_DIGEST_TYPES` C++ enum. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ne-iscsidsc-iscsi_digest_types

const (
	DigestTypeNone DigestType = iota
	DigestTypeCRC32C
)

The various digest types available.

type LoginFlags

type LoginFlags uint32

LoginFlags are used in `LoginOptions`. see the "LoginFlags" section of https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_login_options

const (
	LoginFlagRequireIPSec          LoginFlags = 0x00000001
	LoginFlagMultipathEnabled      LoginFlags = 0x00000002
	LoginFlagAllowPortalHopping    LoginFlags = 0x00000008
	LoginFlagUseRadiusResponse     LoginFlags = 0x00000010
	LoginFlagUseRadiusVerification LoginFlags = 0x00000020
)

See the Windows documentation for an explanation of each of which each of these maps to. The 3rd bit maps to `ISCSI_LOGIN_FLAG_RESERVED1`, and is reserved for Windows' API internal usage.

type LoginOptions

type LoginOptions struct {
	LoginFlags         LoginFlags
	AuthType           *AuthType
	HeaderDigest       *DigestType
	DataDigest         *DigestType
	MaximumConnections *uint32
	DefaultTime2Wait   *uint32
	DefaultTime2Retain *uint32
	Username           *string
	Password           *string
}

LoginOptions maps to the `ISCSI_LOGIN_OPTIONS` C++ struct. All pointer fields are optional and can be left nil. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_login_options

type Portal

type Portal struct {
	// the Windows name
	SymbolicName string
	// IP address or DNS name
	Address string
	// port number - if left empty, defaults to 3260
	Socket *uint16
}

Portal maps to the `ISCSI_TARGET_PORTALW` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_target_portalw

type PortalInfo

type PortalInfo struct {
	Portal
	InitiatorName       string
	InitiatorPortNumber uint32
	SecurityFlags       SecurityFlags
	LoginOptions        LoginOptions
}

PortalInfo aggregates a portal with all the metadata attached to it. It maps to the `ISCSI_TARGET_PORTAL_INFO_EXW` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_target_portal_info_exw

type ScsiAddress

type ScsiAddress struct {
	PortNumber uint8
	PathID     uint8
	TargetID   uint8
	Lun        uint8
}

ScsiAddress maps to the `SCSI_ADDRESS` C++ struct. see https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/content/ntddscsi/ns-ntddscsi-_scsi_address

type SecurityFlags

type SecurityFlags uint64

SecurityFlags are one of`AddIScsiSendTargetPortalW`'s arguments. see the "SecurityFlags" section of https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/nf-iscsidsc-addiscsisendtargetportalw

const (
	SecurityFlagIkeIpsecEnabled        SecurityFlags = 0x00000002
	SecurityFlagMainModeEnabled        SecurityFlags = 0x00000004
	SecurityFlagAggressiveModeEnabled  SecurityFlags = 0x00000008
	SecurityFlagPfsEnabled             SecurityFlags = 0x00000010
	SecurityFlagTransportModePreferred SecurityFlags = 0x00000020
	SecurityFlagTunnelModePreferred    SecurityFlags = 0x00000040
)

The various security flags available.

type SessionID

type SessionID struct {
	AdapterUnique   uint64
	AdapterSpecific uint64
}

SessionID maps to the `ISCSI_UNIQUE_SESSION_ID` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_unique_session_id

type SessionInfo

type SessionInfo struct {
	SessionID      SessionID
	InitiatorName  string
	TargetNodeName string
	TargetName     string
	ISID           [6]byte
	TSID           [2]byte
	Connections    []ConnectionInfo
}

SessionInfo maps to the `ISCSI_SESSION_INFOW` C++ struct. see https://docs.microsoft.com/en-us/windows/desktop/api/iscsidsc/ns-iscsidsc-iscsi_session_infow

type StorageDeviceNumber

type StorageDeviceNumber struct {
	DeviceType      uint32
	DeviceNumber    uint32
	PartitionNumber uint32
}

StorageDeviceNumber maps to the `STORAGE_DEVICE_NUMBER` C++ struct. see https://docs.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-_storage_device_number

type WinAPICallError

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

WinAPICallError is used when a Windows API call fails, and it allows the caller to get some meta-data about the failure.

func NewWinAPICallError

func NewWinAPICallError(procName string, exitCode uintptr) *WinAPICallError

NewWinAPICallError builds a new WinAPICallError.

func (*WinAPICallError) Error

func (err *WinAPICallError) Error() string

func (*WinAPICallError) ExitCode

func (err *WinAPICallError) ExitCode() uintptr

ExitCode returns the numerical exit code.

func (*WinAPICallError) HexCode

func (err *WinAPICallError) HexCode() string

HexCode formats a Windows exit status into the hexadecimal representation one can find in Windows' documentation. see https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d and https://docs.microsoft.com/en-us/windows-hardware/drivers/storage/iscsi-status-qualifiers

func (*WinAPICallError) ProcName

func (err *WinAPICallError) ProcName() string

ProcName returns the name of the proc that failed.