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