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