/* * iSCSI Administration library * * Copyright (C) 2008-2009 Red Hat, Inc. All rights reserved. * Copyright (C) 2008-2009 Hans de Goede * Copyright (C) 2015 Peter Hatina * maintained by open-iscsi@googlegroups.com * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published * by the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * See the file COPYING included with this distribution for more details. */ #ifndef __LIBISCSI_H #define __LIBISCSI_H #include #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #if __GNUC__ >= 4 #define PUBLIC __attribute__ ((visibility("default"))) #else #define PUBLIC #endif /** \brief Maximum length for iSCSI values. * * Maximum length for iSCSI values such as hostnames and parameter values. */ #define LIBISCSI_VALUE_MAXLEN 256 /** \brief supported authentication methods * * This enum lists all supported authentication methods. */ enum libiscsi_auth_t { libiscsi_auth_none /** No authentication */, libiscsi_auth_chap /** CHAP authentication */, }; /** \brief libiscsi context struct * * Note: even though libiscsi uses a context struct, the underlying open-iscsi * code does not, so libiscsi is not thread safe, not even when using one * context per thread! */ struct libiscsi_context; /** \brief iSCSI session timeouts * * Struct holding session timeouts. */ struct libiscsi_session_timeout { int abort_tmo; int lu_reset_tmo; int recovery_tmo; int tgt_reset_tmo; }; /** \brief iSCSI node record * * Struct holding data uniquely identifying an iSCSI node. */ struct libiscsi_node { char name[LIBISCSI_VALUE_MAXLEN] /** iSCSI iqn for the node. */; int tpgt /** Portal group number. */; /* Note open-iscsi has some code in place for multiple connections in one node record and thus multiple address / port combi's, but this does not get used anywhere, so we keep things simple and assume one connection */ char address[NI_MAXHOST] /** Portal hostname or IP-address. */; int port /** Portal port number. */; char iface[LIBISCSI_VALUE_MAXLEN] /** Interface to connect through. */; }; /** \brief libiscsi CHAP authentication information struct * * Struct holding all data needed for CHAP login / authentication. Note that * \e reverse_username may be a 0 length string in which case only forward * authentication will be done. */ struct libiscsi_chap_auth_info { char username[LIBISCSI_VALUE_MAXLEN] /** Username */; char password[LIBISCSI_VALUE_MAXLEN] /** Password */; char reverse_username[LIBISCSI_VALUE_MAXLEN] /** Reverse Username */; char reverse_password[LIBISCSI_VALUE_MAXLEN] /** Reverse Password */; }; /** \brief iSCSI session * * Struct hoding iSCSI session information. */ struct libiscsi_session_info { int sid; struct libiscsi_session_timeout tmo; struct libiscsi_chap_auth_info chap; char targetname[LIBISCSI_VALUE_MAXLEN]; int tpgt; char address[NI_MAXHOST]; int port; char persistent_address[NI_MAXHOST]; int persistent_port; }; /** \brief generic libiscsi authentication information struct * * Struct holding authentication information for discovery and login. */ struct libiscsi_auth_info { enum libiscsi_auth_t method /** Authentication method to use */; union { struct libiscsi_chap_auth_info chap /** Chap specific info */; } /** Union holding method depenend info */; }; /** \brief Initalize libiscsi * * This function creates a libiscsi context and initalizes it. This context * is need to use other libiscsi funtions. * * \return A pointer to the created context, or NULL in case of an error. */ PUBLIC struct libiscsi_context *libiscsi_init(void); /** \brief Cleanup libiscsi used resource * * This function cleanups any used resources and then destroys the passed * context. After this the passed in context may no longer be used! * * \param context libiscsi context to operate on. */ PUBLIC void libiscsi_cleanup(struct libiscsi_context *context); /** \brief Discover iSCSI nodes using sendtargets and add them to the node db. * * This function connects to the given address and port and then tries to * discover iSCSI nodes using the sendtargets protocol. Any found nodes are * added to the local iSCSI node database and are returned in a dynamically * allocated array. * * Note that the (optional) authentication info is for authenticating the * discovery, and is not for the found nodes! If the connection(s) to the * node(s) need authentication too, you can set the username / password for * those (which can be different!) using the libiscsi_node_set_auth() function. * * \param context libiscsi context to operate on. * \param address Hostname or IP-address to connect to. * \param port Port to connect to, or 0 for the default port. * \param auth_info Authentication information, or NULL. * \param nr_found The number of found nodes will be returned * through this pointer if not NULL. * \param found_nodes The address of the dynamically allocated array * of found nodes will be returned through this * pointer if not NULL. The caller must free this * array using free(). * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_discover_sendtargets(struct libiscsi_context *context, const char *address, int port, const struct libiscsi_auth_info *auth_info, int *nr_found, struct libiscsi_node **found_nodes); /** \brief Read iSCSI node info from firmware and add them to the node db. * * This function discovers iSCSI nodes using firmware (ppc or ibft). Any found * nodes are added to the local iSCSI node database and are returned in a * dynamically allocated array. * * Note that unlike sendtargets discovery, this function will also read * authentication info and store that in the database too. * * Note this function currently is a stub which will always return -EINVAL * (IOW it is not yet implemented) * * \param context libiscsi context to operate on. * \param nr_found The number of found nodes will be returned * through this pointer if not NULL. * \param found_nodes The address of the dynamically allocated array * of found nodes will be returned through this * pointer if not NULL. The caller must free this * array using free(). * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_discover_firmware(struct libiscsi_context *context, int *nr_found, struct libiscsi_node **found_nodes); /** \brief Check validity of the given authentication info. * * This function checks the validity of the given authentication info. For * example in case of CHAP, if the username and password are not empty. * * This function is mainly intended for use by language bindings. * * \param context libiscsi context to operate on. * \param auth_info Authentication information to check. * \return 0 on success, otherwise EINVAL. */ PUBLIC int libiscsi_verify_auth_info(struct libiscsi_context *context, const struct libiscsi_auth_info *auth_info); /** \brief Set the authentication info for the given node. * * This function sets the authentication information for the node described by * the given node record. This will overwrite any existing authentication * information. * * This is the way to specify authentication information for nodes found * through sendtargets discovery. * * Note: * 1) This is a convience wrapper around libiscsi_node_set_parameter(), * setting the node.session.auth.* parameters. * 2) For nodes found through firmware discovery the authentication information * has already been set from the firmware. * 3) \e auth_info may be NULL in which case any existing authinfo will be * cleared. * * \param context libiscsi context to operate on. * \param node iSCSI node to set auth information of * \param auth_info Authentication information, or NULL. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_set_auth(struct libiscsi_context *context, const struct libiscsi_node *node, const struct libiscsi_auth_info *auth_info); /** \brief Get the authentication info for the given node. * * This function gets the authentication information for the node described by * the given node record. * * \param context libiscsi context to operate on. * \param node iSCSI node to set auth information of * \param auth_info Pointer to a libiscsi_auth_info struct where * the retreived information will be stored. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_get_auth(struct libiscsi_context *context, const struct libiscsi_node *node, struct libiscsi_auth_info *auth_info); /** \brief Login to an iSCSI node. * * Login to the iSCSI node described by the given node record. * * \param context libiscsi context to operate on. * \param node iSCSI node to login to. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_login(struct libiscsi_context *context, const struct libiscsi_node *node); /** \brief Logout of an iSCSI node. * * Logout of the iSCSI node described by the given node record. * * \param context libiscsi context to operate on. * \param node iSCSI node to logout from. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_logout(struct libiscsi_context *context, const struct libiscsi_node *node); /** \brief Get an array of iSCSI sessions. * * Get the array containing iSCSI sessions' information. * * \param context libiscsi context to operate on. * \param infos Array of iSCSI sessions' information. * Release with free(). * \param nr_sessions The number of elements in \e infos. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_get_session_infos(struct libiscsi_context *context, struct libiscsi_session_info **infos, int *nr_sessions); /** \brief Get session information by session ID. * * \param context libiscsi context to operate on. * \param info iSCSI session information. * \param session Session name. * \return 0 on success, otherwise a standard error code * (from errno.h) */ PUBLIC int libiscsi_get_session_info_by_id(struct libiscsi_context *context, struct libiscsi_session_info *info, const char *session); /** \brief Set an iSCSI parameter for the given node * * Set the given nodes iSCSI parameter named by \e parameter to value \e value. * * \param context libiscsi context to operate on. * \param node iSCSI node to change a parameter from. * \param parameter Name of the parameter to set. * \param value Value to set the parameter too. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_set_parameter(struct libiscsi_context *context, const struct libiscsi_node *node, const char *parameter, const char *value); /** \brief Get the value of an iSCSI parameter for the given node * * Get the value of the given nodes iSCSI parameter named by \e parameter. * * \param context libiscsi context to operate on. * \param node iSCSI node to change a parameter from. * \param parameter Name of the parameter to get. * \param value The retreived value is stored here, this buffer must be * atleast LIBISCSI_VALUE_MAXLEN bytes large. * \return 0 on success, otherwise a standard error code * (from errno.h). */ PUBLIC int libiscsi_node_get_parameter(struct libiscsi_context *context, const struct libiscsi_node *node, const char *parameter, char *value); /** \brief Get human readable string describing the last libiscsi error. * * This function can be called to get a human readable error string when a * libiscsi function has returned an error. This function uses a single buffer * per context, thus the result is only valid as long as no other libiscsi * calls are made on the same context after the failing function call. * * \param context libiscsi context to operate on. * * \return human readable string describing the last libiscsi error. */ PUBLIC const char *libiscsi_get_error_string(struct libiscsi_context *context); /************************** Utility functions *******************************/ /** \brief libiscsi network config struct * * libiscsi network config struct. */ struct libiscsi_network_config { int dhcp /** Using DHCP? (boolean). */; char iface_name[LIBISCSI_VALUE_MAXLEN] /** Interface name. */; char mac_address[LIBISCSI_VALUE_MAXLEN] /** MAC address. */; char ip_address[LIBISCSI_VALUE_MAXLEN] /** IP address. */; char netmask[LIBISCSI_VALUE_MAXLEN] /** Netmask. */; char gateway[LIBISCSI_VALUE_MAXLEN] /** IP of Default gateway. */; char primary_dns[LIBISCSI_VALUE_MAXLEN] /** IP of the Primary DNS. */; char secondary_dns[LIBISCSI_VALUE_MAXLEN] /** IP of the Secondary DNS. */; }; /** \brief Get network configuration information from iscsi firmware * * Function can be called to get the network configuration information * (like dhcp, ip, netmask, default gateway, etc.) from the firmware of a * network adapter with iscsi boot firmware. * * Note that not all fields of the returned struct are necessarilly filled, * unset fields contain a 0 length string. * * \param config pointer to a libiscsi_network_config struct to fill. * * \return 0 on success, ENODEV when no iscsi firmware was found. */ PUBLIC int libiscsi_get_firmware_network_config( struct libiscsi_network_config *config); /** \brief Get the initiator name (iqn) from the iscsi firmware * * Get the initiator name (iqn) from the iscsi firmware. * * \param initiatorname The initiator name is stored here, this buffer must be * atleast LIBISCSI_VALUE_MAXLEN bytes large. * \return 0 on success, ENODEV when no iscsi firmware was found. */ PUBLIC int libiscsi_get_firmware_initiator_name(char *initiatorname); #undef PUBLIC #ifdef __cplusplus } #endif /* __cplusplus */ #endif