path: root/usr/src/man/man3iscsit/it_tgt_create.3iscsit

'\" te
.\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH IT_TGT_CREATE 3ISCSIT "Oct 1, 2008"
.SH NAME
it_tgt_create, it_tgt_setprop, it_tgt_delete, it_tpgt_create, it_tpgt_delete,
it_tgt_free, it_tpgt_free \- create, modify and delete iSCSI Targets
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-liscsit\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libiscsit.h>

\fBint\fR \fBit_tgt_create\fR(\fBit_config_t **\fR\fIcfg\fR, \fBit_tgt_t **\fR\fItgt\fR,
     \fBchar *\fR\fItgt_name\fR);
.fi

.LP
.nf
\fBint\fR \fBit_tgt_setprop\fR(\fBit_config_t *\fR\fIcfg\fR \fBit_tgt_t *\fR\fItgt\fR,
     \fBnvlist_t *\fR\fIproplist\fR, \fBnvlist_t **\fR\fIerrlist\fR);
.fi

.LP
.nf
\fBint\fR \fBit_tgt_delete\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
     \fBboolean_t\fR \fIforce\fR);
.fi

.LP
.nf
\fBint\fR \fBit_tpgt_create\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
     \fBit_tpgt_t **\fR\fItpgt\fR, \fBchar *\fR\fItpg_name\fR, \fBuint16_t\fR \fItpgt_tag\fR);
.fi

.LP
.nf
\fBvoid\fR \fBit_tpgt_delete\fR(\fBit_config_t *\fR\fIcfg\fR, \fBit_tgt_t *\fR\fItgt\fR,
     \fBit_tpgt_t *\fR\fItpgt\fR);
.fi

.LP
.nf
\fBvoid\fR \fBit_tgt_free\fR(\fBit_tgt_t *\fR\fItgt\fR);
.fi

.LP
.nf
\fBvoid\fR \fBit_tpgt_free\fR(\fBit_tpgt_t *\fR\fItpgt\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIcfg\fR\fR
.ad
.RS 13n
a pointer to the iSCSI configuration structure
.RE

.sp
.ne 2
.na
\fB\fItgt\fR\fR
.ad
.RS 13n
a pointer to an iSCSI target structure
.RE

.sp
.ne 2
.na
\fB\fItgt_name\fR\fR
.ad
.RS 13n
the target node name for the target to be created. The name must be in either
IQN or EUI format. If this value is \fINULL\fR, a node name will be generated
automatically in IQN format.
.RE

.sp
.ne 2
.na
\fB\fIproplist\fR\fR
.ad
.RS 13n
a pointer to an \fBnvlist_t\fR containing the target properties to be set
.RE

.sp
.ne 2
.na
\fB\fIerrlist\fR\fR
.ad
.RS 13n
an optional pointer to an \fBnvlist_t\fR that will be used to store specific
errors (if any) when validating target properties
.RE

.sp
.ne 2
.na
\fB\fIforce\fR\fR
.ad
.RS 13n
a boolean value indicating if the target should be set to offline before
removing it from the configuration. If not specified, the operation will fail
if the target is determined to be online
.RE

.sp
.ne 2
.na
\fB\fItpgt\fR\fR
.ad
.RS 13n
a pointer to a target portal group tag structure
.RE

.sp
.ne 2
.na
\fB\fItpgt_name\fR\fR
.ad
.RS 13n
the name of the target portal group to be associated with this target portal
group tag
.RE

.sp
.ne 2
.na
\fB\fItpgt_tag\fR\fR
.ad
.RS 13n
a 16-bit numerical identifier for this target portal group tag. Valid values
are 2 through 65535. If tpgt_tag is '0', \fBit_tpgt_create()\fR will assign an
appropriate tag number. If \fItpgt_tag\fR is != 0, and the requested tag number
is unavailable, another value will be chosen.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBit_tgt_create()\fR function allocates and creates an \fBit_tgt_t\fR
structure representing a new iSCSI target node. If \fItgt_name\fR is
\fINULL\fR, then a unique target node name will be generated automatically.
Otherwise, the value of \fItgt_name\fR will be used as the target node name.
The new \fBit_tgt_t\fR structure is added to the target list
(\fIcfg_tgt_list\fR) in the configuration structure.
.sp
.LP
The \fBit_tgt_setprop()\fR function validates the provided property list and
sets the properties for the specified target.  If \fIerrlist\fR is not
\fINULL\fR, this function returns detailed errors for each property that
failed.  The format for \fIerrlist\fR is \fIkey\fR = \fIproperty\fR,
\fIvalue\fR = \fIerror\fR string.
.sp
.LP
The \fBit_tgt_delete()\fR function removes the target represented by \fItgt\fR
from the configuration. The \fItgt\fR argument is an existing \fBit_tgt_t\fR
structure within the configuration \fIcfg\fR.
.sp
.LP
The \fBit_tpgt_create()\fR function allocates and creates an \fBit_tpgt_t\fR
structure representing a new iSCSI target portal group tag. The new
\fBit_tpgt_t\fR structure is added to the target \fItpgt\fR list
(\fItgt_tpgt_list\fR) in the \fBit_tgt_t\fR structure.
.sp
.LP
The \fBit_tpgt_delete()\fR function removes the target portal group tag
represented by \fItpgt\fR, from the configuration.  The \fItpgt\fR argument is
an existing \fBis_tpgt_t\fR structure within the target \fItgt\fR.
.sp
.LP
The \fBit_tgt_free()\fR function frees an \fBit_tgt_t\fR structure.  If
\fItgt\fR\(->\fInext\fR is not \fINULL\fR, this function frees all structures
in the list.
.sp
.LP
The \fBit_tpgt_free()\fR function deallocates resources of an \fBit_tpgt_t\fR
structure.  If \fItpgt\fR->\fInext\fR is not \fINULL\fR, this function frees
all members of the list.
.sp
.LP
Configuration changes as a result of these functions are not instantiated until
the modified configuration is committed by calling
\fBit_config_commit\fR(3ISCSIT).
.sp
.LP
Target nvlist properties are as follows:
.sp

.sp
.TS
c c c
l l l .
\fBnvlist\fR Key	Type	Valid Values
_
\fBtargetchapuser\fR	\fBstring\fR	any string, or \fBnone\fR to remove
\fBtargetchapsecret\fR	\fBstring\fR	T{
string of at least 12 characters but not more than 255 characters.  secret will be base64 encoded when stored.
T}
\fBalias\fR	\fBstring\fR	any string or \fBnone\fR to remove
\fBauth\fR	\fBstring\fR	\fBradius\fR, \fBchap\fR, or \fBnone\fR
.TE

.SH RETURN VALUES
.sp
.LP
The \fBit_tgt_create()\fR, \fBit_tgt_setprop()\fR, \fBit_tgt_delete()\fR,
\fBit_tpgt_create()\fR, and \fBit_tpgt_delete()\fR functions return 0 on
success and an error value on failure.
.SH ERRORS
.sp
.LP
The \fBit_tgt_create()\fR, \fBit_tgt_setprop()\fR, \fBit_tgt_delete()\fR,
\fBit_tpgt_create()\fR, and \fBit_tpgt_delete()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBE2BIG\fR\fR
.ad
.RS 10n
All tag numbers are already in use.
.RE

.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
The target is online.
.RE

.sp
.ne 2
.na
\fB\fBEEXIST\fR\fR
.ad
.RS 10n
The requested target node name is already configured.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
A parameter or property is invalid.
.RE

.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Resources could not be allocated.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBit_config_commit\fR(3ISCSIT), \fBit_ini_create\fR(3ISCSIT),
\fBit_portal_create\fR(3ISCSIT), \fBit_tpg_create\fR(3ISCSIT),
\fBlibiscsit\fR(3LIB), \fBlibnvpair\fR(3LIB), \fBlibstmf\fR(3LIB),
\fBattributes\fR(5)