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