path: root/usr/src/lib/libiscsitgt/common/libiscsitgt.h

/*
 * CDDL HEADER START
 *
 * 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]
 *
 * CDDL HEADER END
 */

/*
 * Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#ifndef _LIBISCSITGT_H
#define	_LIBISCSITGT_H

#pragma ident	"%Z%%M%	%I%	%E% SMI"

/*
 * Management API for the iSCSI Target.
 */

#ifdef __cplusplus
extern "C" {
#endif

/*
 * These includes resolve
 */
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/iscsi_protocol.h>
#include <sys/scsi/generic/inquiry.h>

#define	EUI64_SIZE	16
#define	VID_SIZE	8
#define	PID_SIZE	16

/*
 * []------------------------------------------------------------------[]
 * | Structures and enums returned by the list functions		|
 * []------------------------------------------------------------------[]
 */

typedef enum { LU_Offline, LU_Online } iscsit_status_t;
typedef enum { Target, Initiator, TPGT } iscsit_obj_type_t;

/*
 * Logical Unit (LU) Structure.
 * Each iSCSI Target has one or more Logical Units.
 */
typedef struct iscsit_lu {
	/* This is the LU number for SCSI commands */
	int		l_num;

	/* Globally unique identifier */
	uint8_t		l_guid[EUI64_SIZE];

	/*
	 * VID/PID used in SCSI INQUIRY responses
	 */
	char		l_vid[VID_SIZE],
			l_pid[PID_SIZE];
	/*
	 * Value will be one of DTYPE_DIRECT, DTYPE_SEQUENTIAL, etc ...
	 * Look at sys/scsi/generic/inquiry.h for full list
	 */
	uint8_t		l_dtype;

	/* Size of device in blocks */
	diskaddr_t	l_size;

	iscsit_status_t	l_status;
} iscsit_lu_t;

/*
 * iSCSI Session information.
 */
typedef struct iscsit_conn {
	char		c_name[ISCSI_MAX_NAME_LEN],
			*c_alias;
} iscsit_conn_t;

typedef struct iscsit_target {
	/* This is the full IQN name of the target */
	char		t_name[ISCSI_MAX_NAME_LEN];

	/*
	 * The Alias which is the same as "friendly name" used during the
	 * creation of the target.
	 */
	char		*t_alias;

	/*
	 * The number of Logical Units associated with this target.
	 * There will always be at least one LU with a value of 0.
	 * If there are more than LU the order is not guaranteed.
	 */
	int		t_lu_count;
	iscsit_lu_t	**t_lu_list;

	/*
	 * A list of initiator which may access this target. This list
	 * may be 0 in length.
	 */
	int		t_acl_count;
	char		**t_acl_list;

	/*
	 * Target Portal Group Tags. A value of zero for the count
	 * is valid.
	 */
	int		t_tpgt_count;
	char		**t_tpgt_list;

	/*
	 * The number of sessions that are currently attached to the
	 * target. Zero is valid.
	 */
	int		t_conn_count;
	iscsit_conn_t	**t_conn_list;
} iscsit_target_t;

/*
 * Information stored locally about initiators. Local initiator information
 * is setup when administrators wish to control access to each target. The
 * use of iSNS will be the prefered method once it's supported.
 */
typedef struct iscsit_initiator {
	char		i_name[ISCSI_MAX_NAME_LEN],
			*i_chap_name;
	/*
	 * While the target daemon has the CHAP secret available it's
	 * never returned. The CHAP name and secret can be changed at
	 * any time. This boolean will indicate if the CHAP secret is set
	 * and if so will cause the daemon to perform unidirectional
	 * authentication.
	 */
	boolean_t	i_chap_secret_set;
} iscsit_initiator_t;

/*
 * The list of IP addresses associated with a Target Portal Group Tag
 */
typedef struct iscsit_tpgt {
	int			t_ip_count;
	struct sockaddr_storage **t_ip_list;
} iscsit_tpgt_t;

/*
 * These are values which are used globally through the target daemon.
 */
typedef struct iscsit_admin {
	/*
	 * This is the targets CHAP information. When an initiator needs
	 * to authenticate the target these values are used when creating
	 * the response.
	 */
	char			*a_chap_name;
	boolean_t		a_chap_secret_set;

	/*
	 * The location of the target configuration and default storage for LUs
	 */
	char			*a_base_directory;

	struct sockaddr_storage	a_radius_server;
	boolean_t		a_radius_secret_set,
				a_isns_discovery;
	struct sockaddr_storage a_isns_ip;
	boolean_t		a_fast_write_ack;
} iscsit_admin_t;

typedef void *iscsit_handle_t;

/*
 * []------------------------------------------------------------------[]
 * | Funtion Prototypes							|
 * []------------------------------------------------------------------[]
 */

/*
 * []------------------------------------------------------------------[]
 * | Functions for ZFS							|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_zfs_share -- advertise a ZFS volume through iSCSI
 * iscsitgt_zfs_unshare -- unadvertise a ZFS volume through iSCSI
 *
 * dataset = this must be a valid ZFS dataset which has a "type" property
 *    of "volume".
 *
 * These functions will return 0 on success and -1 on failure setting errno
 * thusly:
 *
 *    ENODEV - dataset not found
 *    EINVAL - a share parameter has an invalid value
 *    ENOSYS - the option string cannot be understood for any other reason
 */
int iscsitgt_zfs_share(const char *dataset);
int iscsitgt_zfs_unshare(const char *dataset);

/*
 * iscsitgt_zfs_is_shared -- returns 1 and 0 otherwise
 */
int iscsitgt_zfs_is_shared(const char *dataset);

/*
 * []------------------------------------------------------------------[]
 * | Functions to create handles which are used by methods defined below|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_init -- Create a handle for each daemon
 *
 * A future release will enable this library to work to control multiple
 * daemons on different hosts. For now, the argument 'host' should be
 * set to NULL which will indicate the local host.
 */
iscsit_handle_t iscsitgt_init(char *host);

/*
 * iscsitgt_fini -- free resources allocated by iscsitgt_init()
 */
void iscsitgt_fini(iscsit_handle_t h);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for creating base objects					|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_creat_target -- creates a new target/lu
 *
 * h = This is handle which indicates to which target the request is sent.
 *    If NULL, the target daemon on the current host is used.
 * friendly_name = any ASCII string with the following restrictions.
 *    - it must be no more than 163 characters
 *    - it must only contain charcters from the set of 'a-z', 'A-Z', '0-9',
 *      ':', '.', or '-'
 *    The friendly_name will also be used as the iSCSI TargetAlias which
 *    is sent to the initiator as part of the log in parameters.
 * lun = If the friendly_name has never been used before then lun must be 0.
 *    If friendly_name has already been created other luns will be created
 *    under that target. 0 <= lun <= 65535. NOTE: Using LUNs larger than
 *    255 is not guaranteed to work for all initiators.
 * size = The requested size for the device in blocks. There must be
 *    available space on the device for the create to succeed. size may
 *    be zero if, and only if, a 'backing' argument is given which exists.
 * dtype = This indicates which type of emulation is performed by the
 *    daemon. Currently DTYPE_DIRECT, DTYPE_SEQUENTIAL, and DTYPE_UNKNOWN
 *    are supported. A dtype of DTYPE_UNKNOWN indicates to the daemon
 *    that a pass through mode should be used. For the pass through mode
 *    to work 'backing' must be a character device which supports the USCSI
 *    ioctl. For ZVOLs the dtype should be DTYPE_DIRECT.
 * backing = optional location for the backing store. Normally the storage
 *    for the LU is created in the directory supplied to iscsit_mod_adm_store().
 *    If the 'backing' file name doesn't exist *and* a valid device 'size' is
 *    given then the backing store will be created in that location. When the
 *    target/lu is removed this backing store will also be removed.
 *
 * Return codes:
 * EINVAL = one or more of the arguments are invalid
 * ENOSPC = No space remains to create the backing store.
 * EEXIST = A target with the same friendly_name already exists
 */
int iscsitgt_creat_target(iscsit_handle_t h, char *friendly_name,
    int lun, diskaddr_t size, int dtype, char *backing);

/*
 * iscsitgt_creat_initiator -- creates an initiator object
 *
 * Associates a fully compliant iSCSI name (IQN or EUI type) with
 * a really human readable name.
 *
 * h = Handle used to communicate with remote target daemons. A NULL
 *    value may be used to indicate that the local host target daemon
 * friendly_name = Any ASCII string.
 * iqn_name = An initiator IQN or EUI string. There will be no validation
 *    of the name to determine if it complies with RFC3720. This way if
 *    an initiator has a poorly formed name we can still be configured to
 *    work with it.
 *
 * Return codes:
 * 0 = success
 * EEXIST = The friendly_name is already used.
 */
int iscsitgt_creat_initiator(iscsit_handle_t h, char *friendly_name,
    char *iqn_name);

/*
 * iscsitgt_creat_tpgt -- Create a Target Portal Group Tag
 *
 * Once a TPGT object has been created iscsitgt_add_tpgt_ip would be used
 * to associate certain IP addresses with this TPGT. This is used to
 * limit which NICs connections are accepted on for a given target.
 * Once a TPGT is setup it can be added to a target using:
 *     iscsitgt_add_target_tpgt().
 *
 * h = See iscsitgt_creat_target
 * tpgt_num = a value between 1 and 65535 inclusive
 *
 * Return codes:
 * 0 = success
 * EEXIST = A tpgt with that number already exists.
 * EINVAL = TPGT must be a value between 1 and 65535 inclusive
 */
int iscsitgt_creat_tpgt(iscsit_handle_t h, int tpgt_num);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for removing base objects					|
 * []------------------------------------------------------------------[]
 */

/*
 * iscsitgt_rem_target -- Removes a target/LU from the system
 *
 * Logical Unit Number 0 *must* be the last LUN removed from a target
 * If not, an error will be returned. When LUN0 is removed all references
 * to friendly_name are also removed from the system. e.g. Once the LU's
 * are removed there's nothing else required to remove the target.
 *
 * h = See iscsitgt_creat_target()
 * friendly_name = This is the same name used during the creation of
 *    the target.
 * lun = Logical Unit Number
 *
 * Return codes:
 * 0 = success
 * ENOENT = either friendly_name wasn't found or lun not found
 * EINVAL = attempt made to remove LUN0 while other LUs still exist.
 */
int iscsitgt_rem_target(iscsit_handle_t h, char *friendly_name,
    int lun);

/*
 * iscsitgt_rem_initiator -- Removes initiator object
 *
 * This method removes just the initiator object, but not any references
 * to this object. For example let's say an initiator was called
 * payroll_server and that this server was replaced with a new server
 * that had the same function, but with a new IQN value and CHAP secret.
 * The user of this library could then remove the initiator object
 * and create a new one with the changes *without* needing to update all
 * of the target objects that have a reference to 'payroll_server' in
 * their ACLs. This is a security feature. If a target has a reference
 * to an initiator object which doesn't exist, nobody will be able to
 * log into the target. If the daemon we're to remove all references
 * along with the object it would then be possible for an initiator to
 * log into the target during the time the target didn't have a reference.
 *
 * h = See iscsitgt_creat_target()
 * friendly_name = same value as that used during create.
 *
 * Return codes:
 * 0 = success
 * ENOENT = Can't find friendly_name
 */
int iscsitgt_rem_initiator(iscsit_handle_t h, char *friendly_name);

/*
 * iscsitgt_rem_tpgt -- Removes a tpgt object
 *
 * Similar in function to iscsitgt_rem_initiator. This method only
 * removes the TPGT object, but not any references to the object. This
 * alows the administrator to remove an old TPGT and create a new one
 * without needing to update each and every target first.
 *
 * h = See iscsitgt_creat_target
 * tpgt_num = value used during create
 *
 * Return codes:
 * 0 = success
 * ENOENT = tpgt_num wasn't found
 * EINVAL = a value outside of the accepted range for tpgt_num was used.
 */
int iscsitgt_rem_tpgt(iscsit_handle_t h, int tpgt_num);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for adding attributes to base objects			|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_add_target_initiator -- Adds an initiator object to ACL for target
 *
 * h = See iscsitgt_creat_target
 * friendly_name = Existing target
 * initiator = name of initiator object which doesn't need to exist before
 *    it's added.
 *
 * Return codes:
 * 0 = success
 * ENOENT = friendly_name doesn't exist.
 */
int iscsitgt_add_target_initiator(iscsit_handle_t h, char *friendly_name,
    char *initiator);

/*
 * iscsitgt_add_target_tpgt -- adds TPGT to the target
 *
 * h = See iscsitgt_creat_target()
 * friendly_name = Must be a valid target object name
 * tpgt_num = While the TPGT object doesn't need to exist, the value will
 *    be validated to see if it's within the valid range of 1 to 65535 inclusive
 *
 * Return codes:
 * 0 = success
 * ENOENT = friendly_name not found
 * EINVAL = tpgt_num is not within the valid range.
 */
int iscsitgt_add_target_tpgt(iscsit_handle_t h, char *friendly_name,
    int tpgt_num);

/*
 * iscsitgt_add_tpgt_ip -- Adds IP address to TPGT object
 *
 * Return codes:
 * 0 = success
 * ENOENT = tpgt_num doesn't exist
 * EINVAL = tpgt_num is not within the valid range
 */
int iscsitgt_add_tpgt_ip(iscsit_handle_t h, int tpgt_num,
    struct sockaddr_storage *s);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for deleting attributes from base objects			|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_del_target_initiator -- Removes initiator from target ACL
 *
 * h = See iscsitgt_creat_target()
 * friendly_name = target object
 * initiator = initiator object to remove from ACL
 *
 * Return codes:
 * 0 = success
 * ENOENT = friendly_name or initiator don't exist
 */
int iscsitgt_del_target_initiator(iscsit_handle_t h, char *friendly_name,
    char *initiator);

/*
 * iscsitgt_del_target_tpgt -- Removes TPGT from specific target
 *
 * Return codes:
 * 0 = success
 * ENOENT = Either friendly_name or tpgt_num doesn't exist as a valid
 *    type
 * EINVAL = tpgt_num is outside of the valid range (1 to 65535)
 */
int iscsitgt_del_target_tpgt(iscsit_handle_t h, char *friendly_name,
    int tpgt_num);

/*
 * iscsitgt_del_tpgt_ip -- Removes IP address from TPGT
 *
 * Return codes:
 * 0 = success
 * ENOENT = tpgt_num wasn't found or the IP address wasn't found within a valid
 *    tpgt
 * EINVAL = tpgt_num is outside of the valid range (1 to 65535)
 */
int iscsitgt_del_tpgt_ip(iscsit_handle_t h, int tpgt_num,
    struct sockaddr_storage *s);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for modifying singular attributes for base objects	|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsitgt_mode_target_alias -- Modifies the TargetAlias associated with target
 *
 * By default the TargetAlias is the same as that given for the friendly_name.
 * If another name is desired then it can be changed using this interface.
 *
 * h = See iscsitgt_creat_target()
 * friendly_name = target object
 *
 * Return codes:
 * 0 = success
 * ENOENT = friendly_name doesn't exist
 */
int iscsitgt_mod_target_alias(iscsit_handle_t h, char *friendly_name,
    char *alias);
int iscsitgt_mod_target_maxrec(iscsit_handle_t h, char *friendly_name,
    size_t maxrecv);
int iscsitgt_mod_initiator_chap(iscsit_handle_t h,
    char *friendly_name, char *chap_name, char *chap_secret);
int iscsitgt_mod_adm_store(iscsit_handle_t h, char *base);
int iscsitgt_mod_adm_chap(iscsit_handle_t h, char *chap_name,
    char *chap_secret);
int iscsitgt_mod_adm_radius(iscsit_handle_t h, struct sockaddr_storage *s,
    char *secret);
int iscsitgt_mod_adm_isns_discover(iscsit_handle_t h,
    boolean_t find);
int iscsitgt_mod_adm_isns(iscsit_handle_t h,
    struct sockaddr_storage *s);
int iscsitgt_mod_adm_fwa(iscsit_handle_t h, boolean_t enable);

/*
 * []------------------------------------------------------------------[]
 * | Funtions for listing objects					|
 * |									|
 * | NOTE: Each of the following function have a specific free routine	|
 * | which must be called to free the data.				|
 * []------------------------------------------------------------------[]
 */
/*
 * iscsit_list_find -- returns list of specific object names.
 *
 * There are three types of objects which are manipulated by these
 * interfaces (Target, Initiator, and TPGT). This function will return
 * an array of character strings which represent all of the available
 * objects of the specific type. These strings are the same ones that
 * where used during the creation.
 *
 * NOTE: Since there's no locking a call to this this function may
 * return a name which then doesn't exist when the user attempts to
 * get the specific information on that object. This would be caused
 * when another operator deletes an object between the first and second
 * calls.
 */
char **iscsit_list_find(iscsit_handle_t h, iscsit_obj_type_t t);
void iscsit_list_free(char **list);

/*
 * iscsit_list_target -- returns detailed information about a target
 */
iscsit_target_t *iscsit_list_target(iscsit_handle_t h, char *targ);
void iscsit_list_target_free(iscsit_target_t *t);

/*
 * iscsit_list_initiator -- returns detailed information about an initiator
 */
iscsit_initiator_t *iscsit_list_initiator(iscsit_handle_t h, char *initiator);
void iscsit_list_initiator_free(iscsit_initiator_t *t);

/*
 * iscsit_list_tpgt -- returns detailed information about a target port group
 */
iscsit_tpgt_t *iscsit_list_tpgt(iscsit_handle_t h, char *tpgt);
void iscsit_list_tpgt_free(iscsit_tpgt_t *t);

/*
 * iscsit_list_adm -- returns information about the global variables used.
 */
iscsit_admin_t *iscsit_list_adm(iscsit_handle_t h);
void iscsit_list_adm_free(iscsit_admin_t *t);

#ifdef __cplusplus
}
#endif

#endif /* _LIBISCSITGT_H */