246 lines
7.5 KiB
Groff
246 lines
7.5 KiB
Groff
.\" $NetBSD: isns.3,v 1.2 2011/01/16 08:00:01 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Wasabi Systems, Inc.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.Dd October 1, 2009
|
|
.Dt ISNS 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm isns
|
|
.Nd iSNS protocol support library
|
|
.Sh LIBRARY
|
|
.Lb libisns
|
|
.Sh SYNOPSIS
|
|
.In isns.h
|
|
.Ft int
|
|
.Fn isns_init "ISNS_HANDLE *h" "int is_server"
|
|
.Ft void
|
|
.Fn isns_stop "ISNS_HANDLE h"
|
|
.Ft int
|
|
.Fn isns_add_servercon "ISNS_HANDLE h" "int fd" "struct addrinfo *ai"
|
|
.Ft int
|
|
.Fn isns_init_reg_refresh "ISNS_HANDLE h" "const char *node" "int interval"
|
|
.Ft ISNS_TRANS
|
|
.Fn isns_new_trans "ISNS_HANDLE h" "uint16_t func_id" "uint16_t pdu_flags"
|
|
.Ft int
|
|
.Fn isns_add_tlv "ISNS_TRANS t" "uint32_t tag" "int data_len" "const void *data_p"
|
|
.Ft int
|
|
.Fn isns_add_string "ISNS_TRANS t" "uint32_t tag" "const char *s"
|
|
.Ft int
|
|
.Fn isns_send_trans "ISNS_TRANS t" "const struct timespec *timeout_p" "uint32_t *status_p"
|
|
.Ft int
|
|
.Fn isns_get_tlv "ISNS_TRANS t" "int which_tlv" "uint32_t *tag_p" "int data_len_p" "void **data_pp"
|
|
.Ft void
|
|
.Fn isns_free_trans "ISNS_TRANS t"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library exports an API that simplifies Internet Storage Name
|
|
Service (iSNS) client implementations.
|
|
The API defines a transactional model in support of:
|
|
.Pp
|
|
.Bl -bullet -width 3n -offset indent -compact
|
|
.It
|
|
generating iSNS messages composed of iSNS attributes expressed in
|
|
Tag-Length-Value (TLV) data format
|
|
.It
|
|
submitting iSNS Protocol (iSNSP) messages
|
|
.It
|
|
optionally waiting for iSNSP responses
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
does not currently support receipt of iSNS Heartbeat messages, State Change
|
|
Notification (SCN) messages, or Entity Status Inquiry (ESI) messages.
|
|
.Sh INITIALIZATION
|
|
An iSNS client that uses
|
|
.Nm
|
|
must call
|
|
.Fn isns_init
|
|
to initialize the iSNS environment.
|
|
This call will create a thread to handle client-server communication, and
|
|
as such should only be called when thread creation is appropriate (such
|
|
as after a daemonized program forks).
|
|
.Pp
|
|
The value passed as
|
|
.Ar is_server
|
|
is used to set iSNSP message format Flags
|
|
"Sender is the iSNS client" (bit position 16) and "Sender is the iSNS server"
|
|
(bit position 17).
|
|
For now the value 0 (zero) should be passed for
|
|
.Ar is_server .
|
|
The value returned in
|
|
.Ar h
|
|
should be considered opaque by the caller.
|
|
This value is passed unchanged to
|
|
.Fn isns_add_servercon ,
|
|
.Fn isns_init_reg_refresh ,
|
|
.Fn isns_stop ,
|
|
and
|
|
.Fn isns_new_trans .
|
|
.Pp
|
|
.Fn isns_stop
|
|
should be called when the iSNS environment is no longer needed.
|
|
This call will kill any threads created by
|
|
.Fn isns_init .
|
|
.Sh CONFIGURATION
|
|
Following initialization,
|
|
.Fn isns_add_servercon
|
|
should be used to make the iSNS environment aware of the iSNS
|
|
server to which iSNSP queries and requests are to be sent.
|
|
This routine should not be called by a program acting as an iSNS server.
|
|
.Pp
|
|
A connected TCP socket descriptor is passed as parameter
|
|
.Ar fd .
|
|
Parameter
|
|
.Ar ai
|
|
is the address of the remote TCP endpoint.
|
|
It is included so that reconnection may be attempted by
|
|
.Nm
|
|
in the event that the TCP connection is broken.
|
|
.Pp
|
|
Certain iSNS servers will limit registration lifetimes, and will
|
|
refresh registrations after any request from a given iSNS entity.
|
|
The
|
|
.Fn isns_init_reg_refresh
|
|
function offers a way for
|
|
.Nm
|
|
to refresh registrations on behalf of the iSNS client.
|
|
.Pp
|
|
Parameter
|
|
.Ar node
|
|
is the
|
|
.Dq iSCSI Name
|
|
attribute used for the periodic queries.
|
|
It should be the name of an iSCSI node within the registered iSNS entity.
|
|
The desired refresh interval, in seconds, is passed in parameter
|
|
.Ar interval .
|
|
.Sh TRANSACTIONS
|
|
.Fn isns_new_trans
|
|
creates new iSNS transactions.
|
|
.Pp
|
|
Parameter
|
|
.Ar func_id
|
|
is used as the iSNSP message id.
|
|
Parameter
|
|
.Ar pdu_flags
|
|
is used to set iSNSP message format Flags and is
|
|
exposed to allow callers to set flag "Replace flag" (bit position 19).
|
|
This provides callers with a way
|
|
to specify whether a Device Attribute Registration Request is intended to
|
|
update or replace an existing registration.
|
|
This is currently the only use defined for parameter
|
|
.Ar pdu_flags .
|
|
.Pp
|
|
Once a new transaction has been created, callers can specify iSNS attributes
|
|
used for registration and query requests.
|
|
TLV data may be added using either
|
|
.Fn isns_add_tlv
|
|
or
|
|
.Fn isns_add_string .
|
|
.Pp
|
|
Parameter
|
|
.Ar tag
|
|
is the iSNS Tag corresponding to the attribute being added.
|
|
Parameter
|
|
.Ar data_len
|
|
is the length of the attribute value.
|
|
Parameter
|
|
.Ar data_p
|
|
references the attribute value.
|
|
The caller does not need to handle iSNS attribute 4-byte alignment requirements.
|
|
This is handled by the iSNS environment on behalf of the caller.
|
|
.Fn isns_add_string
|
|
may be used if the attribute value is a NUL terminated C string.
|
|
.Pp
|
|
Once a transaction has been populated with any required TLV data,
|
|
.Fn isns_send_trans
|
|
can be used to submit an iSNSP registration or query message.
|
|
.Pp
|
|
Callers that submit iSNSP query messages may need to wait for returned data.
|
|
.Fn isns_send_trans
|
|
supports bounded waits.
|
|
Successful waits, those that do not time out, return the iSNSP response
|
|
status code received in the iSNSP response message.
|
|
If a wait does time out, the value of
|
|
.Ar status_p
|
|
is undefined.
|
|
Callers that do not need to wait for returned data can simply
|
|
pass
|
|
.Dv NULL
|
|
for parameter
|
|
.Ar timeout_p .
|
|
Callers should set parameter
|
|
.Ar status_p
|
|
to
|
|
.Dv NULL
|
|
if not waiting.
|
|
.Pp
|
|
.Fn isns_get_tlv
|
|
is used to retrieve TLV data returned in a transaction.
|
|
The first call to
|
|
.Fn isns_get_tlv
|
|
should pass the value
|
|
.Dv ISNS_TLV_FIRST
|
|
for parameter
|
|
.Ar which_tlv .
|
|
Each subsequent TLV can be retrieved by passing in
|
|
.Dv ISNS_TLV_NEXT
|
|
in place of
|
|
.Dv ISNS_TLV_FIRST .
|
|
.Pp
|
|
When a caller is done with a transaction, having submitted either a
|
|
registration or a query message and retrieved any returned TLV data,
|
|
.Fn isns_free_trans
|
|
should be used to release resources used by the transaction.
|
|
.Sh RETURN VALUES
|
|
.Fn isns_init ,
|
|
.Fn isns_add_servercon ,
|
|
.Fn isns_init_reg_refresh ,
|
|
.Fn isns_add_tlv ,
|
|
.Fn isns_add_string ,
|
|
and
|
|
.Fn isns_send_trans
|
|
return 0 on success, or \-1 on failure.
|
|
.Fn isns_new_trans
|
|
returns 0 on success, or
|
|
.Dv ISNS_INVALID_TRANS
|
|
on failure.
|
|
.Fn isns_get_tlv
|
|
returns 0 on success, or
|
|
.Er ENOENT
|
|
if there are no TLVs to retrieve.
|
|
.Sh HISTORY
|
|
.Nm
|
|
first appeared in
|
|
.Nx 6.0 .
|
|
The
|
|
.Nm
|
|
implementation was contributed to the
|
|
.Nx
|
|
Foundation by Wasabi Systems, Inc.
|