usr/src/man/man3iscsit/it_tgt_create.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_TGT_CREATE 3ISCSIT "Oct 1, 2008"
   7 .SH NAME
   8 it_tgt_create, it_tgt_setprop, it_tgt_delete, it_tpgt_create, it_tpgt_delete,
   9 it_tgt_free, it_tpgt_free \- create, modify and delete iSCSI Targets
  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_tgt_create\fR(\fBit_config_t **\fR\fIcfg\fR, \fBit_tgt_t **\fR\fItgt\fR,
  17      \fBchar *\fR\fItgt_name\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBint\fR \fBit_tgt_setprop\fR(\fBit_config_t *\fR\fIcfg\fR \fBit_tgt_t *\fR\fItgt\fR,
  23      \fBnvlist_t *\fR\fIproplist\fR, \fBnvlist_t **\fR\fIerrlist\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBit_tgt_delete\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
  29      \fBboolean_t\fR \fIforce\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBit_tpgt_create\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
  35      \fBit_tpgt_t **\fR\fItpgt\fR, \fBchar *\fR\fItpg_name\fR, \fBuint16_t\fR \fItpgt_tag\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBvoid\fR \fBit_tpgt_delete\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
  41      \fBit_tpgt_t *\fR\fItpgt\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBvoid\fR \fBit_tgt_free\fR(\fBit_tgt_t *\fR\fItgt\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBvoid\fR \fBit_tpgt_free\fR(\fBit_tpgt_t *\fR\fItpgt\fR);
  52 .fi
  53
  54 .SH PARAMETERS
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIcfg\fR\fR
  59 .ad
  60 .RS 13n
  61 a pointer to the iSCSI configuration structure
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fItgt\fR\fR
  68 .ad
  69 .RS 13n
  70 a pointer to an iSCSI target structure
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fItgt_name\fR\fR
  77 .ad
  78 .RS 13n
  79 the target node name for the target to be created. The name must be in either
  80 IQN or EUI format. If this value is \fINULL\fR, a node name will be generated
  81 automatically in IQN format.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIproplist\fR\fR
  88 .ad
  89 .RS 13n
  90 a pointer to an \fBnvlist_t\fR containing the target properties to be set
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fIerrlist\fR\fR
  97 .ad
  98 .RS 13n
  99 an optional pointer to an \fBnvlist_t\fR that will be used to store specific
 100 errors (if any) when validating target properties
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fIforce\fR\fR
 107 .ad
 108 .RS 13n
 109 a boolean value indicating if the target should be set to offline before
 110 removing it from the configuration. If not specified, the operation will fail
 111 if the target is determined to be online
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fItpgt\fR\fR
 118 .ad
 119 .RS 13n
 120 a pointer to a target portal group tag structure
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fItpgt_name\fR\fR
 127 .ad
 128 .RS 13n
 129 the name of the target portal group to be associated with this target portal
 130 group tag
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fItpgt_tag\fR\fR
 137 .ad
 138 .RS 13n
 139 a 16-bit numerical identifier for this target portal group tag. Valid values
 140 are 2 through 65535. If tpgt_tag is '0', \fBit_tpgt_create()\fR will assign an
 141 appropriate tag number. If \fItpgt_tag\fR is != 0, and the requested tag number
 142 is unavailable, another value will be chosen.
 143 .RE
 144
 145 .SH DESCRIPTION
 146 .sp
 147 .LP
 148 The \fBit_tgt_create()\fR function allocates and creates an \fBit_tgt_t\fR
 149 structure representing a new iSCSI target node. If \fItgt_name\fR is
 150 \fINULL\fR, then a unique target node name will be generated automatically.
 151 Otherwise, the value of \fItgt_name\fR will be used as the target node name.
 152 The new \fBit_tgt_t\fR structure is added to the target list
 153 (\fIcfg_tgt_list\fR) in the configuration structure.
 154 .sp
 155 .LP
 156 The \fBit_tgt_setprop()\fR function validates the provided property list and
 157 sets the properties for the specified target.  If \fIerrlist\fR is not
 158 \fINULL\fR, this function returns detailed errors for each property that
 159 failed.  The format for \fIerrlist\fR is \fIkey\fR = \fIproperty\fR,
 160 \fIvalue\fR = \fIerror\fR string.
 161 .sp
 162 .LP
 163 The \fBit_tgt_delete()\fR function removes the target represented by \fItgt\fR
 164 from the configuration. The \fItgt\fR argument is an existing \fBit_tgt_t\fR
 165 structure within the configuration \fIcfg\fR.
 166 .sp
 167 .LP
 168 The \fBit_tpgt_create()\fR function allocates and creates an \fBit_tpgt_t\fR
 169 structure representing a new iSCSI target portal group tag. The new
 170 \fBit_tpgt_t\fR structure is added to the target \fItpgt\fR list
 171 (\fItgt_tpgt_list\fR) in the \fBit_tgt_t\fR structure.
 172 .sp
 173 .LP
 174 The \fBit_tpgt_delete()\fR function removes the target portal group tag
 175 represented by \fItpgt\fR, from the configuration.  The \fItpgt\fR argument is
 176 an existing \fBis_tpgt_t\fR structure within the target \fItgt\fR.
 177 .sp
 178 .LP
 179 The \fBit_tgt_free()\fR function frees an \fBit_tgt_t\fR structure.  If
 180 \fItgt\fR\(->\fInext\fR is not \fINULL\fR, this function frees all structures
 181 in the list.
 182 .sp
 183 .LP
 184 The \fBit_tpgt_free()\fR function deallocates resources of an \fBit_tpgt_t\fR
 185 structure.  If \fItpgt\fR->\fInext\fR is not \fINULL\fR, this function frees
 186 all members of the list.
 187 .sp
 188 .LP
 189 Configuration changes as a result of these functions are not instantiated until
 190 the modified configuration is committed by calling
 191 \fBit_config_commit\fR(3ISCSIT).
 192 .sp
 193 .LP
 194 Target nvlist properties are as follows:
 195 .sp
 196
 197 .sp
 198 .TS
 199 c c c
 200 l l l .
 201 \fBnvlist\fR Key        Type    Valid Values
 202 _
 203 \fBtargetchapuser\fR    \fBstring\fR    any string, or \fBnone\fR to remove
 204 \fBtargetchapsecret\fR  \fBstring\fR    T{
 205 string of at least 12 characters but not more than 255 characters.  secret will be base64 encoded when stored.
 206 T}
 207 \fBalias\fR     \fBstring\fR    any string or \fBnone\fR to remove
 208 \fBauth\fR      \fBstring\fR    \fBradius\fR, \fBchap\fR, or \fBnone\fR
 209 .TE
 210
 211 .SH RETURN VALUES
 212 .sp
 213 .LP
 214 The \fBit_tgt_create()\fR, \fBit_tgt_setprop()\fR, \fBit_tgt_delete()\fR,
 215 \fBit_tpgt_create()\fR, and \fBit_tpgt_delete()\fR functions return 0 on
 216 success and an error value on failure.
 217 .SH ERRORS
 218 .sp
 219 .LP
 220 The \fBit_tgt_create()\fR, \fBit_tgt_setprop()\fR, \fBit_tgt_delete()\fR,
 221 \fBit_tpgt_create()\fR, and \fBit_tpgt_delete()\fR functions will fail if:
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBE2BIG\fR\fR
 226 .ad
 227 .RS 10n
 228 All tag numbers are already in use.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBEBUSY\fR\fR
 235 .ad
 236 .RS 10n
 237 The target is online.
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBEEXIST\fR\fR
 244 .ad
 245 .RS 10n
 246 The requested target node name is already configured.
 247 .RE
 248
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBEINVAL\fR\fR
 253 .ad
 254 .RS 10n
 255 A parameter or property is invalid.
 256 .RE
 257
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBENOMEM\fR\fR
 262 .ad
 263 .RS 10n
 264 Resources could not be allocated.
 265 .RE
 266
 267 .SH ATTRIBUTES
 268 .sp
 269 .LP
 270 See \fBattributes\fR(5) for descriptions of the following attributes:
 271 .sp
 272
 273 .sp
 274 .TS
 275 box;
 276 c | c
 277 l | l .
 278 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 279 _
 280 Interface Stability     Committed
 281 _
 282 MT-Level        MT-Safe
 283 .TE
 284
 285 .SH SEE ALSO
 286 .sp
 287 .LP
 288 \fBit_config_commit\fR(3ISCSIT), \fBit_ini_create\fR(3ISCSIT),
 289 \fBit_portal_create\fR(3ISCSIT), \fBit_tpg_create\fR(3ISCSIT),
 290 \fBlibiscsit\fR(3LIB), \fBlibnvpair\fR(3LIB), \fBlibstmf\fR(3LIB),
 291 \fBattributes\fR(5)