1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 /* 22 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 * Use is subject to license terms. 24 */ 25 26 #ifndef _LIBISCSIT_H 27 #define _LIBISCSIT_H 28 29 #ifndef _KERNEL 30 #include <libnvpair.h> 31 #include <sys/socket.h> 32 #endif 33 34 #include <sys/iscsit/iscsit_common.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #define MAX_TARGETS 32 /* maximum targets that may be created */ 41 #define MAX_TPGT 256 42 #define CFG_TPGTLIST "tpgt-list" 43 44 /* 45 * Object Hierarchy 46 * 47 * _______________________ 48 * | | 49 * | iSCSI Target Config | 50 * | it_config_t | 51 * |_______________________| 52 * | | 53 * | | 54 * | | ________ ________ ________ 55 * | | | | | | | | 56 * | | | Target |-->| Target |-- - - -->| Target | 57 * | | |________| |________| |________| 58 * | | | 59 * | | | 60 * | | | 61 * | | | ______ ______ 62 * | | | | | | | 63 * | | +----->| TPGT |-- - - -->| TPGT | 64 * | | |______| |______| 65 * | | | | 66 * | +--+ | | 67 * | | _______ _______ | ______ | 68 * | | | | | |<--+ | |<--+ 69 * | +->| TPG |-->| TPG |-- - - -->| TPG | 70 * | |_______| |_______| |______| 71 * | 72 * | ___________ ___________ ___________ 73 * | | | | | | | 74 * +---->| Initiator |-->| Initiator |-- - - -->| Initiator | 75 * | Context | | Context | | Context | 76 * |___________| |___________| |___________| 77 * 78 * 79 * it_config_t includes a list of global properties 80 * 81 * Targets include a list of properties which override the global properties 82 * if set 83 * 84 * Initiators also include a list of properties but never inherit properties 85 * from the global config. 86 */ 87 88 /* 89 * Function: it_config_load() 90 * 91 * Allocate and create an it_config_t structure representing the 92 * current iSCSI configuration. This structure is compiled using 93 * the 'provider' data returned by stmfGetProviderData(). If there 94 * is no provider data associated with iscsit, the it_config_t 95 * structure will be set to a default configuration. 96 * 97 * Parameters: 98 * cfg A C representation of the current iSCSI configuration 99 * 100 * Return Values: 101 * 0 Success 102 * ENOMEM Could not allocate resources 103 * EINVAL Invalid parameter 104 */ 105 int 106 it_config_load(it_config_t **cfg); 107 108 /* 109 * Function: it_config_commit() 110 * 111 * Informs the iscsit service that the configuration has changed and 112 * commits the new configuration to persistent store by calling 113 * stmfSetProviderData. This function can be called multiple times 114 * during a configuration sequence if necessary. 115 * 116 * Parameters: 117 * cfg A C representation of the current iSCSI configuration 118 * 119 * Return Values: 120 * 0 Success 121 * ENOMEM Could not allocate resources 122 * EINVAL Invalid it_config_t structure 123 * STMF_ERROR_SERVICE_DATA_VERSION Configuration was updated by another 124 * client. See stmfSetProviderDataProt(). 125 */ 126 int 127 it_config_commit(it_config_t *cfg); 128 129 /* 130 * Function: it_config_setprop() 131 * 132 * Validate the provided property list and set the global properties 133 * for iSCSI Target. If errlist is not NULL, returns detailed 134 * errors for each property that failed. The format for errorlist 135 * is key = property, value = error string. 136 * 137 * Parameters: 138 * 139 * cfg The current iSCSI configuration obtained from 140 * it_config_load() 141 * proplist nvlist_t containing properties for this target. 142 * errlist (optional) nvlist_t of errors encountered when 143 * validating the properties. 144 * 145 * Return Values: 146 * 0 Success 147 * ENOMEM Could not allocate resources 148 * EINVAL Invalid property 149 * 150 */ 151 int 152 it_config_setprop(it_config_t *cfg, nvlist_t *proplist, nvlist_t **errlist); 153 154 /* 155 * Function: it_config_free() 156 * 157 * Free any resources associated with the it_config_t structure. 158 * 159 * Parameters: 160 * cfg A C representation of the current iSCSI configuration 161 */ 162 void 163 it_config_free(it_config_t *cfg); 164 165 /* 166 * Function: it_tgt_create() 167 * 168 * Allocate and create an it_tgt_t structure representing a new iSCSI 169 * target node. If tgt_name is NULL, then a unique target node name will 170 * be generated automatically. Otherwise, the value of tgt_name will be 171 * used as the target node name. The new it_tgt_t structure is added to 172 * the target list (cfg_tgt_list) in the configuration structure, and the 173 * new target will not be instantiated until the modified configuration 174 * is committed by calling it_config_commit(). 175 * 176 * Parameters: 177 * cfg The current iSCSI configuration obtained from 178 * it_config_load() 179 * tgt Pointer to an iSCSI target structure 180 * tgt_name The target node name for the target to be created. 181 * The name must be in either IQN or EUI format. If 182 * this value is NULL, a node name will be generated 183 * automatically in IQN format. 184 * 185 * Return Values: 186 * 0 Success 187 * ENOMEM Could not allocate resources 188 * EINVAL Invalid parameter or creating would create too many 189 * targets. 190 * EEXIST The requested target node name is already configured 191 * EFAULT Invalid iSCSI target name 192 */ 193 int 194 it_tgt_create(it_config_t *cfg, it_tgt_t **tgt, char *tgt_name); 195 196 /* 197 * Function: it_tgt_setprop() 198 * 199 * Validate the provided property list and set the properties for 200 * the specified target. If errlist is not NULL, returns detailed 201 * errors for each property that failed. The format for errorlist 202 * is key = property, value = error string. 203 * 204 * Parameters: 205 * 206 * cfg The current iSCSI configuration obtained from 207 * it_config_load() 208 * tgt Pointer to an iSCSI target structure 209 * proplist nvlist_t containing properties for this target. 210 * errlist (optional) nvlist_t of errors encountered when 211 * validating the properties. 212 * 213 * Return Values: 214 * 0 Success 215 * ENOMEM Could not allocate resources 216 * EINVAL Invalid property 217 * 218 */ 219 int 220 it_tgt_setprop(it_config_t *cfg, it_tgt_t *tgt, nvlist_t *proplist, 221 nvlist_t **errlist); 222 223 224 /* 225 * Function: it_tgt_delete() 226 * 227 * Delete target represented by 'tgt', where 'tgt' is an existing 228 * it_tgt_t structure within the configuration 'cfg'. The target removal 229 * will not take effect until the modified configuration is committed 230 * by calling it_config_commit(). 231 * 232 * Parameters: 233 * cfg The current iSCSI configuration obtained from 234 * it_config_load() 235 * tgt Pointer to an iSCSI target structure 236 * force Set the target to offline before removing it from 237 * the config. If not specified, the operation will 238 * fail if the target is determined to be online. 239 * 240 * Return Values: 241 * 0 Success 242 * EBUSY Target is online 243 */ 244 int 245 it_tgt_delete(it_config_t *cfg, it_tgt_t *tgt, boolean_t force); 246 247 /* 248 * Function: it_tpgt_create() 249 * 250 * Allocate and create an it_tpgt_t structure representing a new iSCSI 251 * target portal group tag. The new it_tpgt_t structure is added to the 252 * target tpgt list (tgt_tpgt_list) in the it_tgt_t structure. The new 253 * target portal group tag will not be instantiated until the modified 254 * configuration is committed by calling it_config_commit(). 255 * 256 * Parameters: 257 * cfg The current iSCSI configuration obtained from 258 * it_config_load() 259 * tgt Pointer to the iSCSI target structure associated 260 * with the target portal group tag 261 * tpgt Pointer to a target portal group tag structure 262 * tpg_name The name of the TPG to be associated with this TPGT 263 * tpgt_tag 16-bit numerical identifier for this TPGT. Valid 264 * values are 2 through 65535. If tpgt_tag is '0', 265 * this function will assign an appropriate tag number. 266 * If tpgt_tag is != 0, and the requested number is 267 * unavailable, another value will be chosen. 268 * 269 * Return Values: 270 * 0 Success 271 * ENOMEM Could not allocate resources 272 * EINVAL Invalid parameter 273 * EEXIST Specified TPG is already associated with the target 274 * E2BIG All tag numbers already in use 275 */ 276 int 277 it_tpgt_create(it_config_t *cfg, it_tgt_t *tgt, it_tpgt_t **tpgt, 278 char *tpg_name, uint16_t tpgt_tag); 279 280 /* 281 * Function: it_tpgt_delete() 282 * 283 * Delete the target portal group tag represented by 'tpgt', where 284 * 'tpgt' is an existing is_tpgt_t structure within the target 'tgt'. 285 * The target portal group tag removal will not take effect until the 286 * modified configuation is committed by calling it_config_commit(). 287 * 288 * Parameters: 289 * cfg The current iSCSI configuration obtained from 290 * it_config_load() 291 * tgt Pointer to the iSCSI target structure associated 292 * with the target portal group tag 293 * tpgt Pointer to a target portal group tag structure 294 */ 295 void 296 it_tpgt_delete(it_config_t *cfg, it_tgt_t *tgt, it_tpgt_t *tpgt); 297 298 /* 299 * Function: it_tpg_create() 300 * 301 * Allocate and create an it_tpg_t structure representing a new iSCSI 302 * target portal group. The new it_tpg_t structure is added to the global 303 * tpg list (cfg_tgt_list) in the it_config_t structure. The new target 304 * portal group will not be instantiated until the modified configuration 305 * is committed by calling it_config_commit(). 306 * 307 * Parameters: 308 * cfg The current iSCSI configuration obtained from 309 * it_config_load() 310 * tpg Pointer to the it_tpg_t structure representing 311 * the target portal group 312 * tpg_name Identifier for the target portal group 313 * portal_ip_port A string containing an appropriatedly formatted 314 * IP address:port. Both IPv4 and IPv6 addresses are 315 * permitted. This value becomes the first portal in 316 * the TPG -- applications can add additional values 317 * using it_portal_create() before committing the TPG. 318 * Return Values: 319 * 0 Success 320 * ENOMEM Cannot allocate resources 321 * EINVAL Invalid parameter 322 * EEXIST Portal already configured for another portal group 323 * associated with this target. 324 */ 325 int 326 it_tpg_create(it_config_t *cfg, it_tpg_t **tpg, char *tpg_name, 327 char *portal_ip_port); 328 329 /* 330 * Function: it_tpg_delete() 331 * 332 * Delete target portal group represented by 'tpg', where 'tpg' is an 333 * existing it_tpg_t structure within the global configuration 'cfg'. 334 * The target portal group removal will not take effect until the 335 * modified configuration is committed by calling it_config_commit(). 336 * 337 * Parameters: 338 * cfg The current iSCSI configuration obtained from 339 * it_config_load() 340 * tpg Pointer to the it_tpg_t structure representing 341 * the target portal group 342 * force Remove this target portal group even if it's 343 * associated with one or more targets. 344 * 345 * Return Values: 346 * 0 Success 347 * EINVAL Invalid parameter 348 * EBUSY Portal group associated with one or more targets. 349 */ 350 int 351 it_tpg_delete(it_config_t *cfg, it_tpg_t *tpg, boolean_t force); 352 353 /* 354 * Function: it_portal_create() 355 * 356 * Add an it_portal_t structure representing a new portal to the specified 357 * target portal group. The change to the target portal group will not take 358 * effect until the modified configuration is committed by calling 359 * it_config_commit(). 360 * 361 * Parameters: 362 * cfg The current iSCSI configration obtained from 363 * it_config_load() 364 * tpg Pointer to the it_tpg_t structure representing the 365 * target portal group or "none" to remove 366 * portal Pointer to the it_portal_t structure representing 367 * the portal 368 * portal_ip_port A string containing an appropriately formatted 369 * IP address or IP address:port in either IPv4 or 370 * IPv6 format. 371 * Return Values: 372 * 0 Success 373 * ENOMEM Could not allocate resources 374 * EINVAL Invalid parameter 375 * EEXIST Portal already configured for another portal group 376 */ 377 int 378 it_portal_create(it_config_t *cfg, it_tpg_t *tpg, it_portal_t **portal, 379 char *portal_ip_port); 380 381 /* 382 * Function: it_portal_delete() 383 * 384 * Remove the specified portal from the specified target portal group. 385 * The portal removal will not take effect until the modified configuration 386 * is committed by calling it_config_commit(). 387 * 388 * Parameters: 389 * cfg The current iSCSI configration obtained from 390 * it_config_load() 391 * tpg Pointer to the it_tpg_t structure representing the 392 * target portal group 393 * portal Pointer to the it_portal_t structure representing 394 * the portal 395 */ 396 void 397 it_portal_delete(it_config_t *cfg, it_tpg_t *tpg, it_portal_t *portal); 398 399 /* 400 * Function: it_ini_create() 401 * 402 * Add an initiator context to the global configuration. The new 403 * initiator context will not be instantiated until the modified 404 * configuration is committed by calling it_config_commit(). 405 * 406 * Parameters: 407 * cfg The current iSCSI configration obtained from 408 * it_config_load() 409 * ini Pointer to the it_ini_t structure representing 410 * the initiator context. 411 * ini_node_name The iSCSI node name of the remote initiator. 412 * 413 * Return Values: 414 * 0 Success 415 * ENOMEM Could not allocate resources 416 * EINVAL Invalid parameter. 417 * EEXIST Initiator already configured 418 * EFAULT Invalid initiator name 419 */ 420 int 421 it_ini_create(it_config_t *cfg, it_ini_t **ini, char *ini_node_name); 422 423 /* 424 * Function: it_ini_setprop() 425 * 426 * Validate the provided property list and set the initiator properties. 427 * If errlist is not NULL, returns detailed errors for each property 428 * that failed. The format for errorlist is 429 * key = property, value = error string. 430 * 431 * Parameters: 432 * 433 * ini The initiator being updated. 434 * proplist nvlist_t containing properties for this target. 435 * errlist (optional) nvlist_t of errors encountered when 436 * validating the properties. 437 * 438 * Return Values: 439 * 0 Success 440 * ENOMEM Could not allocate resources 441 * EINVAL Invalid property 442 * 443 */ 444 int 445 it_ini_setprop(it_ini_t *ini, nvlist_t *proplist, nvlist_t **errlist); 446 447 /* 448 * Function: it_ini_delete() 449 * 450 * Remove the specified initiator context from the global configuration. 451 * The removal will not take effect until the modified configuration is 452 * committed by calling it_config_commit(). 453 * 454 * Parameters: 455 * cfg The current iSCSI configration obtained from 456 * it_config_load() 457 * ini Pointer to the it_ini_t structure representing 458 * the initiator context. 459 */ 460 void 461 it_ini_delete(it_config_t *cfg, it_ini_t *ini); 462 463 /* 464 * Function: it_config_free() 465 * 466 * Free any resources associated with the it_config_t structure. 467 * 468 * Parameters: 469 * cfg A C representation of the current iSCSI configuration 470 */ 471 void 472 it_config_free(it_config_t *cfg); 473 474 /* 475 * Function: it_tgt_free() 476 * 477 * Frees an it_tgt_t structure. If tgt_next is not NULL, frees 478 * all structures in the list. 479 */ 480 void 481 it_tgt_free(it_tgt_t *tgt); 482 483 /* 484 * Function: it_tpgt_free() 485 * 486 * Deallocates resources of an it_tpgt_t structure. If tpgt->next 487 * is not NULL, frees all members of the list. 488 */ 489 void 490 it_tpgt_free(it_tpgt_t *tpgt); 491 492 /* 493 * Function: it_tpg_free() 494 * 495 * Deallocates resources associated with an it_tpg_t structure. 496 * If tpg->next is not NULL, frees all members of the list. 497 */ 498 void 499 it_tpg_free(it_tpg_t *tpg); 500 501 /* 502 * Function: it_ini_free() 503 * 504 * Deallocates resources of an it_ini_t structure. If ini->next is 505 * not NULL, frees all members of the list. 506 */ 507 void 508 it_ini_free(it_ini_t *ini); 509 510 /* 511 * Function: validate_iscsi_name() 512 * 513 * Ensures the passed-in string is a valid IQN or EUI iSCSI name 514 */ 515 boolean_t 516 validate_iscsi_name(char *in_name); 517 518 #ifdef __cplusplus 519 } 520 #endif 521 522 #endif /* _LIBISCSIT_H */ 523