usr/src/man/man3iscsit/it_config_load.3iscsit

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH IT_CONFIG_LOAD 3ISCSIT "Oct 1, 2008"
   7 .SH NAME
   8 it_config_load, it_config_commit, it_config_setprop, it_config_free \- set and
   9 retrieve configuration data for the iSCSI Target Port Provider
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-liscsit\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <libiscsit.h>
  15
  16 \fBint\fR \fBit_config_load\fR(\fBit_config_t **\fR\fIcfg\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBit_config_commit\fR(\fBit_config_t *\fR\fIcfg\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBit_config_setprop\fR(\fBit_config_t *\fR\fIcfg\fR, \fBnvlist_t *\fR\fIproplist\fR,
  27      \fBnvlist_t **\fR\fIerrlist\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBit_config_free\fR(\fBit_config_t *\fR\fIcfg\fR);
  33 .fi
  34
  35 .SH PARAMETERS
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIcfg\fR\fR
  40 .ad
  41 .RS 12n
  42 a pointer to the iSCSI configuration structure
  43 .RE
  44
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIproplist\fR\fR
  49 .ad
  50 .RS 12n
  51 a pointer to an \fBnvlist_t\fR containing the global properties to be set
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIerrlist\fR\fR
  58 .ad
  59 .RS 12n
  60 an optional pointer to an \fBnvlist_t\fR that will be used to store specific
  61 errors (if any) when validating global properties
  62 .RE
  63
  64 .SH DESCRIPTION
  65 .sp
  66 .LP
  67 The \fBit_config_load()\fR function allocates and creates an \fBit_config_t\fR
  68 structure representing the current iSCSI configuration. This structure is
  69 compiled using the "provider" data returned by
  70 \fBstmfGetProviderData\fR(3STMF). If there is no provider data associated with
  71 iscsit, the \fBit_config_t\fR structure is set to a default configuration.
  72 .sp
  73 .LP
  74 The \fBit_config_commit()\fR function informs the iscsit service that the
  75 configuration has changed and commits the new configuration to the persistent
  76 store by calling \fBstmfSetProviderData\fR(3STMF). This function can be called
  77 multiple times during a configuration sequence, if necessary.
  78 .sp
  79 .LP
  80 The \fBit_config_setprop()\fR function validates the provided property list and
  81 sets the global properties for iSCSI Target. If \fIerrlist\fR is not
  82 \fINULL\fR, this function returns detailed errors for each property that
  83 failed. The format for \fIerrorlist\fR is \fIkey\fR = \fIproperty\fR,
  84 \fIvalue\fR = \fIerror\fR string.
  85 .sp
  86 .LP
  87 The \fBit_config_free()\fR function frees resources associated with the
  88 \fBit_config_t\fR structure.
  89 .sp
  90 .LP
  91 Global nvlist properties are as follows:
  92 .sp
  93
  94 .sp
  95 .TS
  96 c c c
  97 l l l .
  98 \fBnvlist\fR Key        Type    Valid Values
  99 _
 100 \fBalias\fR     \fBstring\fR    any string
 101 \fBauth\fR      \fBstring\fR    \fBradius\fR, \fBchap\fR, or \fBnone\fR
 102 \fBisns\fR      \fBboolean\fR   \fBB_TRUE\fR, \fBB_FALSE\fR
 103 \fBisnsserver\fR        \fBstring\fR array      T{
 104 Array of portal specifications of the form IPaddress:port.  Port is optional; if not specified, the default iSNS port number of 3205 will be used.  IPv6 addresses should be enclosed in square brackets '[' ']'.  If "none" is specified, all defined iSNS servers will be removed from the configuration.
 105 T}
 106 \fBradiusserver\fR      \fBstring\fR    T{
 107 IPaddress:port specification as described for 'isnsserver'
 108 T}
 109 \fBradiussecret\fR      \fBstring\fR    T{
 110 string of at least 12 characters but not more than 255 characters.  secret will be base64 encoded when stored.
 111 T}
 112 .TE
 113
 114 .SH RETURN VALUES
 115 .sp
 116 .LP
 117 The \fBit_config_load()\fR, \fBit_config_commit()\fR, and
 118 \fBit_config_setprop()\fR functions return 0 on success and an error value on
 119 failure.
 120 .SH ERRORS
 121 .sp
 122 .LP
 123 The \fBit_config_load()\fR, \fBit_config_commit()\fR, and
 124 \fBit_config_setprop()\fR functions will fail if:
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBEINVAL\fR\fR
 129 .ad
 130 .RS 10n
 131 A parameter or property is invalid.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBENOMEM\fR\fR
 138 .ad
 139 .RS 10n
 140 Resources could not be allocated.
 141 .RE
 142
 143 .sp
 144 .LP
 145 The \fBit_config_commit()\fR function will also fail if:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBSTMF_ERROR_SERVICE_DATA_VERSION\fR\fR
 150 .ad
 151 .sp .6
 152 .RS 4n
 153 The configuration was updated by another client. See
 154 \fBstmfSetProviderData\fR(3STMF).
 155 .RE
 156
 157 .SH ATTRIBUTES
 158 .sp
 159 .LP
 160 See \fBattributes\fR(5) for descriptions of the following attributes:
 161 .sp
 162
 163 .sp
 164 .TS
 165 box;
 166 c | c
 167 l | l .
 168 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 169 _
 170 Interface Stability     Committed
 171 _
 172 MT-Level        MT-Safe
 173 .TE
 174
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBit_ini_create\fR(3ISCSIT), \fBit_portal_create\fR(3ISCSIT),
 179 \fBit_tgt_create\fR(3ISCSIT), \fBit_tpg_create\fR(3ISCSIT),
 180 \fBlibiscsit\fR(3LIB), \fBlibnvpair\fR(3LIB), \fBlibstmf\fR(3LIB),
 181 \fBstmfGetProviderData\fR(3STMF), \fBstmfSetProviderData\fR(3STMF),
 182 \fBattributes\fR(5)