1.\" $NetBSD: isns.3,v 1.2 2011/01/16 08:00:01 wiz Exp $ 2.\" 3.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Wasabi Systems, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.Dd October 1, 2009 30.Dt ISNS 3 31.Os 32.Sh NAME 33.Nm isns 34.Nd iSNS protocol support library 35.Sh LIBRARY 36.Lb libisns 37.Sh SYNOPSIS 38.In isns.h 39.Ft int 40.Fn isns_init "ISNS_HANDLE *h" "int is_server" 41.Ft void 42.Fn isns_stop "ISNS_HANDLE h" 43.Ft int 44.Fn isns_add_servercon "ISNS_HANDLE h" "int fd" "struct addrinfo *ai" 45.Ft int 46.Fn isns_init_reg_refresh "ISNS_HANDLE h" "const char *node" "int interval" 47.Ft ISNS_TRANS 48.Fn isns_new_trans "ISNS_HANDLE h" "uint16_t func_id" "uint16_t pdu_flags" 49.Ft int 50.Fn isns_add_tlv "ISNS_TRANS t" "uint32_t tag" "int data_len" "const void *data_p" 51.Ft int 52.Fn isns_add_string "ISNS_TRANS t" "uint32_t tag" "const char *s" 53.Ft int 54.Fn isns_send_trans "ISNS_TRANS t" "const struct timespec *timeout_p" "uint32_t *status_p" 55.Ft int 56.Fn isns_get_tlv "ISNS_TRANS t" "int which_tlv" "uint32_t *tag_p" "int data_len_p" "void **data_pp" 57.Ft void 58.Fn isns_free_trans "ISNS_TRANS t" 59.Sh DESCRIPTION 60The 61.Nm 62library exports an API that simplifies Internet Storage Name 63Service (iSNS) client implementations. 64The API defines a transactional model in support of: 65.Pp 66.Bl -bullet -width 3n -offset indent -compact 67.It 68generating iSNS messages composed of iSNS attributes expressed in 69Tag-Length-Value (TLV) data format 70.It 71submitting iSNS Protocol (iSNSP) messages 72.It 73optionally waiting for iSNSP responses 74.El 75.Pp 76.Nm 77does not currently support receipt of iSNS Heartbeat messages, State Change 78Notification (SCN) messages, or Entity Status Inquiry (ESI) messages. 79.Sh INITIALIZATION 80An iSNS client that uses 81.Nm 82must call 83.Fn isns_init 84to initialize the iSNS environment. 85This call will create a thread to handle client-server communication, and 86as such should only be called when thread creation is appropriate (such 87as after a daemonized program forks). 88.Pp 89The value passed as 90.Ar is_server 91is used to set iSNSP message format Flags 92"Sender is the iSNS client" (bit position 16) and "Sender is the iSNS server" 93(bit position 17). 94For now the value 0 (zero) should be passed for 95.Ar is_server . 96The value returned in 97.Ar h 98should be considered opaque by the caller. 99This value is passed unchanged to 100.Fn isns_add_servercon , 101.Fn isns_init_reg_refresh , 102.Fn isns_stop , 103and 104.Fn isns_new_trans . 105.Pp 106.Fn isns_stop 107should be called when the iSNS environment is no longer needed. 108This call will kill any threads created by 109.Fn isns_init . 110.Sh CONFIGURATION 111Following initialization, 112.Fn isns_add_servercon 113should be used to make the iSNS environment aware of the iSNS 114server to which iSNSP queries and requests are to be sent. 115This routine should not be called by a program acting as an iSNS server. 116.Pp 117A connected TCP socket descriptor is passed as parameter 118.Ar fd . 119Parameter 120.Ar ai 121is the address of the remote TCP endpoint. 122It is included so that reconnection may be attempted by 123.Nm 124in the event that the TCP connection is broken. 125.Pp 126Certain iSNS servers will limit registration lifetimes, and will 127refresh registrations after any request from a given iSNS entity. 128The 129.Fn isns_init_reg_refresh 130function offers a way for 131.Nm 132to refresh registrations on behalf of the iSNS client. 133.Pp 134Parameter 135.Ar node 136is the 137.Dq iSCSI Name 138attribute used for the periodic queries. 139It should be the name of an iSCSI node within the registered iSNS entity. 140The desired refresh interval, in seconds, is passed in parameter 141.Ar interval . 142.Sh TRANSACTIONS 143.Fn isns_new_trans 144creates new iSNS transactions. 145.Pp 146Parameter 147.Ar func_id 148is used as the iSNSP message id. 149Parameter 150.Ar pdu_flags 151is used to set iSNSP message format Flags and is 152exposed to allow callers to set flag "Replace flag" (bit position 19). 153This provides callers with a way 154to specify whether a Device Attribute Registration Request is intended to 155update or replace an existing registration. 156This is currently the only use defined for parameter 157.Ar pdu_flags . 158.Pp 159Once a new transaction has been created, callers can specify iSNS attributes 160used for registration and query requests. 161TLV data may be added using either 162.Fn isns_add_tlv 163or 164.Fn isns_add_string . 165.Pp 166Parameter 167.Ar tag 168is the iSNS Tag corresponding to the attribute being added. 169Parameter 170.Ar data_len 171is the length of the attribute value. 172Parameter 173.Ar data_p 174references the attribute value. 175The caller does not need to handle iSNS attribute 4-byte alignment requirements. 176This is handled by the iSNS environment on behalf of the caller. 177.Fn isns_add_string 178may be used if the attribute value is a NUL terminated C string. 179.Pp 180Once a transaction has been populated with any required TLV data, 181.Fn isns_send_trans 182can be used to submit an iSNSP registration or query message. 183.Pp 184Callers that submit iSNSP query messages may need to wait for returned data. 185.Fn isns_send_trans 186supports bounded waits. 187Successful waits, those that do not time out, return the iSNSP response 188status code received in the iSNSP response message. 189If a wait does time out, the value of 190.Ar status_p 191is undefined. 192Callers that do not need to wait for returned data can simply 193pass 194.Dv NULL 195for parameter 196.Ar timeout_p . 197Callers should set parameter 198.Ar status_p 199to 200.Dv NULL 201if not waiting. 202.Pp 203.Fn isns_get_tlv 204is used to retrieve TLV data returned in a transaction. 205The first call to 206.Fn isns_get_tlv 207should pass the value 208.Dv ISNS_TLV_FIRST 209for parameter 210.Ar which_tlv . 211Each subsequent TLV can be retrieved by passing in 212.Dv ISNS_TLV_NEXT 213in place of 214.Dv ISNS_TLV_FIRST . 215.Pp 216When a caller is done with a transaction, having submitted either a 217registration or a query message and retrieved any returned TLV data, 218.Fn isns_free_trans 219should be used to release resources used by the transaction. 220.Sh RETURN VALUES 221.Fn isns_init , 222.Fn isns_add_servercon , 223.Fn isns_init_reg_refresh , 224.Fn isns_add_tlv , 225.Fn isns_add_string , 226and 227.Fn isns_send_trans 228return 0 on success, or \-1 on failure. 229.Fn isns_new_trans 230returns 0 on success, or 231.Dv ISNS_INVALID_TRANS 232on failure. 233.Fn isns_get_tlv 234returns 0 on success, or 235.Er ENOENT 236if there are no TLVs to retrieve. 237.Sh HISTORY 238.Nm 239first appeared in 240.Nx 6.0 . 241The 242.Nm 243implementation was contributed to the 244.Nx 245Foundation by Wasabi Systems, Inc. 246