/*****************************************************************************\ * $Id: ipmiconsole.h,v 1.89 2010-08-03 00:10:59 chu11 Exp $ ***************************************************************************** * Copyright (C) 2007-2012 Lawrence Livermore National Security, LLC. * Copyright (C) 2006-2007 The Regents of the University of California. * Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). * Written by Albert Chu * UCRL-CODE-221226 * * This file is part of Ipmiconsole, a set of IPMI 2.0 SOL libraries * and utilities. For details, see http://www.llnl.gov/linux/. * * Ipmiconsole 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 3 of the License, or (at your * option) any later version. * * Ipmiconsole 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. * * You should have received a copy of the GNU General Public License along * with Ipmiconsole. If not, see . \*****************************************************************************/ #ifndef IPMICONSOLE_H #define IPMICONSOLE_H #ifdef __cplusplus extern "C" { #endif #include #include /* * Libipmiconsole version * * MAJOR - Incremented when interfaces are changed or removed. * Interfaces may be binary incompatible. When incremented, MINOR * and PATCH are zeroed. * * MINOR - Incremented when interfaces are added. Interfaces are * binary compatible with older minor versions. When incremented, * PATCH is zeroed. * * PATCH - Incremented when interfaces are not changed. Typically * incremented due to bug fixes or minor features. Interfaces are * forward and backward compatible to other PATCH versions. */ #define LIBIPMICONSOLE_VERSION_MAJOR 1 #define LIBIPMICONSOLE_VERSION_MINOR 2 #define LIBIPMICONSOLE_VERSION_PATCH 2 /* * IPMI Console Error Codes */ #define IPMICONSOLE_ERR_SUCCESS 0 #define IPMICONSOLE_ERR_CTX_NULL 1 #define IPMICONSOLE_ERR_CTX_INVALID 2 #define IPMICONSOLE_ERR_ALREADY_SETUP 3 #define IPMICONSOLE_ERR_NOT_SETUP 4 #define IPMICONSOLE_ERR_CTX_NOT_SUBMITTED 5 #define IPMICONSOLE_ERR_CTX_IS_SUBMITTED 6 #define IPMICONSOLE_ERR_PARAMETERS 7 #define IPMICONSOLE_ERR_HOSTNAME_INVALID 8 #define IPMICONSOLE_ERR_IPMI_2_0_UNAVAILABLE 9 #define IPMICONSOLE_ERR_CIPHER_SUITE_ID_UNAVAILABLE 10 #define IPMICONSOLE_ERR_USERNAME_INVALID 11 #define IPMICONSOLE_ERR_PASSWORD_INVALID 12 #define IPMICONSOLE_ERR_K_G_INVALID 13 #define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_INSUFFICIENT 14 #define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_CANNOT_BE_OBTAINED 15 #define IPMICONSOLE_ERR_SOL_UNAVAILABLE 16 #define IPMICONSOLE_ERR_SOL_INUSE 17 #define IPMICONSOLE_ERR_SOL_STOLEN 18 #define IPMICONSOLE_ERR_SOL_REQUIRES_ENCRYPTION 19 #define IPMICONSOLE_ERR_SOL_REQUIRES_NO_ENCRYPTION 20 #define IPMICONSOLE_ERR_BMC_BUSY 21 #define IPMICONSOLE_ERR_BMC_ERROR 22 #define IPMICONSOLE_ERR_BMC_IMPLEMENTATION 23 #define IPMICONSOLE_ERR_CONNECTION_TIMEOUT 24 #define IPMICONSOLE_ERR_SESSION_TIMEOUT 25 #define IPMICONSOLE_ERR_EXCESS_RETRANSMISSIONS_SENT 26 #define IPMICONSOLE_ERR_EXCESS_ERRORS_RECEIVED 27 #define IPMICONSOLE_ERR_OUT_OF_MEMORY 28 #define IPMICONSOLE_ERR_TOO_MANY_OPEN_FILES 29 #define IPMICONSOLE_ERR_SYSTEM_ERROR 30 #define IPMICONSOLE_ERR_INTERNAL_ERROR 31 #define IPMICONSOLE_ERR_ERRNUMRANGE 32 /* * Debug Flags * * Utilized with ipmiconsole_engine_init() or with struct * ipmiconsole_engine_config below for debugging. * * When used with ipmiconsole_engine_init(), enables debugging in * libipmiconsole global activities, such as the libipmiconsole engine * threads. * * When used with struct ipmiconsole_engine_config and a context, * enables debugging specific to an IPMI connection with a specific * host. * * STDOUT - Output debugging to stdout * STDERR - Output debugging to stderr * SYSLOG - Output debugging to the Syslog * FILE - Output debugging to files in current working directory * IPMI_PACKETS - Dump IPMI Packets too * DEFAULT - Informs library to use default, may it be standard * or configured via libipmiconsole.conf. */ #define IPMICONSOLE_DEBUG_STDOUT 0x00000001 #define IPMICONSOLE_DEBUG_STDERR 0x00000002 #define IPMICONSOLE_DEBUG_SYSLOG 0x00000004 #define IPMICONSOLE_DEBUG_FILE 0x00000008 #define IPMICONSOLE_DEBUG_IPMI_PACKETS 0x00000010 #define IPMICONSOLE_DEBUG_DEFAULT 0xFFFFFFFF /* * IPMI Privilege Constants * * Utilized with struct ipmiconsole_ipmi_config below to specify a * privilege level to authenticate with. */ #define IPMICONSOLE_PRIVILEGE_USER 0 #define IPMICONSOLE_PRIVILEGE_OPERATOR 1 #define IPMICONSOLE_PRIVILEGE_ADMIN 2 /* * Workaround Flags * * Utilized with struct ipmiconsole_ipmi_config below to specify * workarounds for specific motherboard manufacturers. * * AUTHENTICATION_CAPABILITIES * * This workaround flag will skip early checks for username * capabilities, authentication capabilities, and K_g support and * allow IPMI authentication to succeed. It works around multiple * issues in which the remote system does not properly report username * capabilities, authentication capabilities, or K_g status. * * INTEL_2_0_SESSION * * This workaround flag will work around several Intel IPMI 2.0 * authentication issues. The issues covered include padding of * usernames, automatic acceptance of a RAKP 4 response integrity * check when using the integrity algorithm MD5-128, and password * truncation if the authentication algorithm is HMAC-MD5-128. * * SUPERMICRO_2_0_SESSION * * This workaround option will work around several Supermicro IPMI 2.0 * authentication issues on motherboards w/ Peppercon IPMI firmware. * The issues covered include handling invalid length authentication * codes. * * SUN_2_0_SESSION * * This workaround flag will work work around several Sun IPMI 2.0 * authentication issues. The issues covered include invalid lengthed * hash keys, improperly hashed keys, and invalid cipher suite * records. This workaround automatically includes the * OPEN_SESSION_PRIVILEGE workaround. * * OPEN_SESSION_PRIVILEGE * * This workaround flag will slightly alter FreeIPMI's IPMI 2.0 * connection protocol to workaround an invalid hashing algorithm used * by the remote system. The privilege level sent during the Open * Session stage of an IPMI 2.0 connection is used for hashing keys * instead of the privilege level sent during the RAKP1 connection * stage. This workaround is automatically triggered with the * SUN_2_0_SESSION workaround. * * NON_EMPTY_INTEGRITY_CHECK_VALUE * * This workaround option will work around an invalid integrity check * value during an IPMI 2.0 session establishment when using Cipher * Suite ID 0. The integrity check value should be 0 length, however * the remote motherboard responds with a non-empty field. * * NO_CHECKSUM_CHECK * * This workaround option will work around motheboards that calculate * checksums incorrectly in IPMI command responses, but the packet is * otherwise valid. Users are cautioned on the use of this option, as * it removes some validation of packet integrity. However, it is * unlikely to be an issue in most situations. * * SERIAL_ALERTS_DEFERRED * * This workaround option will set serial alerts to be deferred * instead of have them be failures. This works around motherboards * that perform IPMI over serial along with IPMI serial over LAN. * * INCREMENT_SOL_PACKET_SEQUENCE * * This workaround option will increment the SOL payload packet * sequence number under dire circumstances. Normally SOL should * never do this, however some motherboards have shown to get "stuck" * due to an internal bug on the motherboard. This workaround can * help in getting the BMC un-stuck. * * IGNORE_SOL_PAYLOAD_SIZE * * This workaround flag will not check for valid SOL payload sizes and * assume a proper set. It works around remote systems that report * invalid IPMI 2.0 SOL payload sizes. * * IGNORE_SOL_PORT * * This workaround flag will ignore alternate SOL ports specified * during the protocol. It works around remote systems that report * invalid alternate SOL ports. * * SKIP_SOL_ACTIVATION_STATUS * * This workaround flag will not check the current activation status * of SOL during the protocol setup. It works around remote systems * that do not properly support this command. * * SKIP_CHANNEL_PAYLOAD_SUPPORT * * This workaround flag will skip the portion of the protocol that * checks if SOL is supported on the current channel. It works around * remote systems that do not properly support this command. * * DEFAULT * * Informs library to use default, may it be the standard default or * a default configured via libipmiconsole.conf. * * Note: The non-logical bitmask order below is set for future * expansion and matching w/ libfreeipmi. */ #define IPMICONSOLE_WORKAROUND_AUTHENTICATION_CAPABILITIES 0x00000001 #define IPMICONSOLE_WORKAROUND_INTEL_2_0_SESSION 0x00000002 #define IPMICONSOLE_WORKAROUND_SUPERMICRO_2_0_SESSION 0x00000004 #define IPMICONSOLE_WORKAROUND_SUN_2_0_SESSION 0x00000008 #define IPMICONSOLE_WORKAROUND_OPEN_SESSION_PRIVILEGE 0x00000010 #define IPMICONSOLE_WORKAROUND_NON_EMPTY_INTEGRITY_CHECK_VALUE 0x00000020 #define IPMICONSOLE_WORKAROUND_NO_CHECKSUM_CHECK 0x00000040 #define IPMICONSOLE_WORKAROUND_SERIAL_ALERTS_DEFERRED 0x00000080 #define IPMICONSOLE_WORKAROUND_INCREMENT_SOL_PACKET_SEQUENCE 0x00000100 #define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PAYLOAD_SIZE 0x01000000 #define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PORT 0x02000000 #define IPMICONSOLE_WORKAROUND_SKIP_SOL_ACTIVATION_STATUS 0x04000000 #define IPMICONSOLE_WORKAROUND_SKIP_CHANNEL_PAYLOAD_SUPPORT 0x08000000 #define IPMICONSOLE_WORKAROUND_DEFAULT 0xFFFFFFFF /* * Engine Flags * * Utilized with struct ipmiconsole_engine_config below to alter * libipmiconsole engine behavior. * * CLOSE_FD * * By default, the ipmiconsole engine will not close the file * descriptor (returned by ipmiconsole_ctx_fd()) when an error occurs * within the ipmiconsole engine (such as a session timeout). A user * will subsequently see an EOF on a read() or an EPIPE on a write() * to know an error occurred. * * This flag will inform the engine to close the file descriptor on * error. This will change the behavior of how the user should * program with the file descriptor. For example, calls to read() and * write() would likely return with EBADF errors instead of EOF or * EPIPE errors respectively. Calls to select() may return with EBADF * errors and calls to poll() could result in POLLNVAL returned * events. * * OUTPUT_ON_SOL_ESTABLISHED * * When submitting a context to the engine non-blocking, another way * to determine if the SOL session has been established is if data has * output from the remote console and is available for you to read. * Under most circumstances, this isn't a controllable situation. * * This flag will inform the engine to output a single NUL character * ('\0') to the console once a SOL session has been established. If * the CLOSE_FD flag isn't used above, this would allow the user to * expect an EOF vs. 1 byte of data on a read() to determine if the * SOL session has failed or succeeded. The user may choose to output * the NUL anyways (it should do no harm) or simply throw out the * first byte ever read from remote console. * * LOCK_MEMORY * * Inform libipmiconsole to lock memory to prevent sensitive * information (such as usernames and passwords) to be non-swappable. * * SERIAL_KEEPALIVE * * On some motherboards, it's been observed that IPMI connections * between the IPMI client and remote BMC/server can stay alive while * the remote server's internal connection between the BMC and serial * chip can be lost. This has been observed under several situations, * such as when the remote system is rebooted or a IPMI SOL session is * stolen. * * The affect is that this loss of the serial connection will not be * noticed by the IPMI client until serial data is transfered from the * client to the BMC and a timeout (or similar error) eventually occurs. * The IPMI client must then reconnect to restablish the session. * * This is a severe problem for IPMI clients that predominantly log * serial data or display serial output without user interactivity. * From the IPMI client perspective, there is simply no output from * the serial port and no error has actually occurred. * * This option will inform the libipmiconsole engine to send serial * keepalive packets in addition to the IPMI keepalive packets that * normally keep a connection alive. The serial keepalive packets are * standard SOL payload packets, but contain a single NUL character in * them. The single NUL character is to ensure that the underlying * serial receiver is alive and functioning. Retransmission and * timeouts are handled identically to normal IPMI packets in the code * (e.g. as if somebody typed a character). The serial keepalive * packets are dispatched if a SOL packet response has not been * received within the length of time of a session timeout. * * This option is highly recommended for IPMI clients that do not have * high user interactivity, as this may discover broken connections * far more quickly. However, caution should be maintained, as the * NUL character byte may affect the remote system depending on what * input it may or may not be expecting. * * SERIAL_KEEPALIVE_EMPTY * * This option is identical to SERIAL_KEEPALIVE, except that the * serial keepalive packets are empty and without character data. On * some motherboards, this may be sufficient to deal with the "serial * keepalive" issue and character data need not be sent with each * packet. On some systems though, a SOL packet without character * data may not be ACKed, and therefore the keepalive fails. * * DEFAULT * * Informs library to use default, may it be the standard default or * a default configured via libipmiconsole.conf. */ #define IPMICONSOLE_ENGINE_CLOSE_FD 0x00000001 #define IPMICONSOLE_ENGINE_OUTPUT_ON_SOL_ESTABLISHED 0x00000002 #define IPMICONSOLE_ENGINE_LOCK_MEMORY 0x00000004 #define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE 0x00000008 #define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE_EMPTY 0x00000010 #define IPMICONSOLE_ENGINE_DEFAULT 0xFFFFFFFF /* * Behavior Flags * * Utilized with struct ipmiconsole_protocol_config below to atler * SOL connection behavior. * * ERROR_ON_SOL_INUSE * * Under most circumstances, if SOL is detected as being in use, * libipmiconsole will attempt to deactivate the earlier SOL session * and activate the SOL session under the current one. This default * behavior exists for several reasons, most notably that earlier SOL * sessions may have not been able to be deactivated properly. This * security flag changes the default behavior to return an error if * SOL is already detected as being in use. If it is detected as in * use, the errnum returned from ipmiconsole_ctx_errnum() would be * IPMICONSOLE_ERR_SOL_INUSE. * * DEACTIVATE_ONLY * * Only attempt to deactivate the SOL session. If an SOL session is * not active, do nothing. * * DEACTIVATE_ALL_INSTANCES * * When a SOL session is deactivated via the DEACTIVATE_ONLY flag, * only the currently configured SOL payload instance will be * deactivated, not any other instance. This flag will inform * libipmiconsole to deactivate all presently activated instances. * This may be useful in a few circumstances where a user might want * to deactivate all current sessions. * * DEFAULT * * Informs library to use default, may it be the standard default or * a default configured via libipmiconsole.conf. */ #define IPMICONSOLE_BEHAVIOR_ERROR_ON_SOL_INUSE 0x00000001 #define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ONLY 0x00000002 #define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ALL_INSTANCES 0x00000004 #define IPMICONSOLE_BEHAVIOR_DEFAULT 0xFFFFFFFF /* * Context Status * * Returned by ipmiconsole_ctx_status() below. * * ERROR * * An error has occurred retrieving the status. * * NOT_SUBMITTED * * The context has not been submitted to the engine. * * SUBMITTED * * The context has been submitted to the engine. SOL has not been * established and an error has not yet occurred. * * SOL_ERROR * * The context has received an error during SOL establishment. * * SOL_ESTABLISHED * * The context has established a SOL session. * */ enum ipmiconsole_ctx_status { IPMICONSOLE_CTX_STATUS_ERROR = -1, IPMICONSOLE_CTX_STATUS_NOT_SUBMITTED = 0, IPMICONSOLE_CTX_STATUS_SUBMITTED = 1, IPMICONSOLE_CTX_STATUS_SOL_ERROR = 2, IPMICONSOLE_CTX_STATUS_SOL_ESTABLISHED = 3, }; typedef enum ipmiconsole_ctx_status ipmiconsole_ctx_status_t; /* * ipmiconsole_ipmi_config * * IPMI configuration for a connection to a remote IPMI machine. * Defaults can be modified using the libipmiconsole.conf file. * * username * * BMC username. Pass NULL ptr for default username. Standard * default is the null (e.g. empty) username. Maximum length of 16 * bytes. * * password * * BMC password. Pass NULL ptr for default password. Standard * default is the null (e.g. empty) password. Maximum length of 20 * bytes. * * k_g * * BMC Key for 2-key authentication. Pass NULL ptr to use the * default. Standard default is the null (e.g. empty) k_g, * which will use the password as the BMC key. The k_g key need not * be an ascii string. * * k_g_len * * Length of k_g. Necessary b/c k_g may contain null values in its * key. Maximum length of 20 bytes. * * privilege_level * * privilege level to authenticate with. * * Supported privilege levels: * * IPMICONSOLE_PRIVILEGE_USER * IPMICONSOLE_PRIVILEGE_OPERATOR * IPMICONSOLE_PRIVILEGE_ADMIN * * Pass < 0 for default. Standard default is * IPMICONSOLE_PRIVILEGE_ADMIN. * * cipher_suite_id * * Cipher suite identifier to determine authentication, integrity, * and confidentiality algorithms to use. * * Supported Cipher Suite IDs * (Key: A - Authentication Algorithm * I - Integrity Algorithm * C - Confidentiality Algorithm) * * 0 - A = None; I = None; C = None * 1 - A = HMAC-SHA1; I = None; C = None * 2 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = None * 3 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = AES-CBC-128 * 6 - A = HMAC-MD5; I = None; C = None * 7 - A = HMAC-MD5; I = HMAC-MD5-128; C = None * 8 - A = HMAC-MD5; I = HMAC-MD5-128; C = AES-CBC-128 * 11 - A = HMAC-MD5; I = MD5-128; C = None * 12 - A = HMAC-MD5; I = MD5-128; C = AES-CBC-128 * 15 - A = HMAC-SHA256; I = None; C = None * 16 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = None * 17 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = AES-CBC-128 * * Pass < 0 for default. Standard default is 3. * * workaround_flags * * Bitwise OR of flags indicating IPMI implementation changes. Some * BMCs which are non-compliant and may require a workaround flag * for correct operation. Pass IPMICONSOLE_WORKAROUND_DEFAULT for * default. Standard default is 0, no modifications to the IPMI * protocol. */ struct ipmiconsole_ipmi_config { char *username; char *password; unsigned char *k_g; unsigned int k_g_len; int privilege_level; int cipher_suite_id; unsigned int workaround_flags; }; /* * ipmiconsole_protocol_config * * Configuration information for the IPMI protocol management. * Defaults can be modified using the libipmiconsole.conf file. * * session_timeout_len * * Specifies the session timeout length in milliseconds. Pass <= 0 * for default. Standard default is 60000 (60 seconds). * * retransmission_timeout_len * * Specifies the packet retransmission timeout length in * milliseconds. Pass <= 0 for default. Standard default is * 500 (0.5 seconds). * * retransmission_backoff_count * * Specifies the packet retransmission count until retransmission * timeout lengths will be backed off. Pass <= 0 for default. * Standard default is 2. * * keepalive_timeout_len * * Specifies the session timeout length in milliseconds until a * keepalive packet is sent. Pass <= 0 for default. Standard * default is 20000 (20 seconds). * * retransmission_keepalive_timeout_len * * Specifies the keepalive packet retransmission timeout length in * milliseconds. Pass <= 0 for default. Standard default is * 5000 (5 seconds). * * acceptable_packet_errors_count * * Specifies the maximum number of consecutive packet errors that * can be received from a remote BMC before an error is returned and * the session ended. Pass <= 0 for default. Standard * default is 16. * * Note: This has been added to the behavior of the IPMI engine due * to issues where remote BMCs can become "un-synced" with sequence * numbers due to a network kernel boot. It is possible a stream of * packets can be sent to the remote client with session sequence * numbers that are excessively outside of the acceptable window * range. * * maximum_retransmission_count * * Specifies the maximum number of retransmissions that can be sent * for any IPMI packet before an error is returned and the session * ended. Pass <= 0 for default. Standard default is 16. * * Note: This has been added to the behavior of the IPMI engine due * to issues where remote BMCs can become "un-synced" with sequence * numbers due to a network kernel boot. It is possible for some * packets (in particular 'ping' packets to keep an IPMI session * alive) to be accepted by the remote BMC, but not SOL packets. * */ struct ipmiconsole_protocol_config { int session_timeout_len; int retransmission_timeout_len; int retransmission_backoff_count; int keepalive_timeout_len; int retransmission_keepalive_timeout_len; int acceptable_packet_errors_count; int maximum_retransmission_count; }; /* * ipmiconsole_engine_config * * Configuration information for how the engine should interact with * the user or API. Defaults can be modified using the * libipmiconsole.conf file. * * engine_flags * * Bitwise OR of flags indicating how the ipmiconsole engine should * behave for a particular context. Pass IPMICONSOLE_ENGINE_DEFAULT * for default. Standard default is 0. * * behavior_flags * * Bitwise OR of flags indicating any protocol behavior that should * be changed from the default. Pass IPMICONSOLE_BEHAVIOR_DEFAULT * for default. Standard default is 0. * * debug_flags * * Bitwise OR of flags indicating how debug output should (or should * not) be output. Pass IPMICONSOLE_DEBUG_DEFAULT for default. * Standard default is 0. * */ struct ipmiconsole_engine_config { unsigned int engine_flags; unsigned int behavior_flags; unsigned int debug_flags; }; /* * Context Config Option * * Used for setting or getting advanced configuration options. See * ipmiconsole_ctx_set_config_option() and * ipmiconsole_ctx_get_config_option(). * * SOL_PAYLOAD_INSTANCE * * The SOL payload instance number to be used. Defaults to 1 and has * range of 1 to 15. Most systems only support a single instance, * however a few allow users to access multiple. They could be used * to allow multiple users to see the same serial session, or allow * users to access different serial sessions behind a device. It is * not commonly available or necessary when communicating via SOL to a * single server. The SOL payload instance number is specified and * retrieved via a pointer to an unsigned int. * */ enum ipmiconsole_ctx_config_option { IPMICONSOLE_CTX_CONFIG_OPTION_SOL_PAYLOAD_INSTANCE = 0, }; typedef enum ipmiconsole_ctx_config_option ipmiconsole_ctx_config_option_t; #define IPMICONSOLE_THREAD_COUNT_MAX 32 typedef struct ipmiconsole_ctx *ipmiconsole_ctx_t; /* * Ipmiconsole_callback * * Function prototype for a callback function. * ipmiconsole_engine_submit() below. */ typedef void (*Ipmiconsole_callback)(void *); /* * ipmiconsole_engine_init * * Initialize the ipmiconsole engine. Engine threads will be created * which will manage SOL sessions for the user. This function must be * called before ipmi console contexts can be submitted into the * engine. This call will also parse and load alternate defaults from * the libipmiconsole.conf defaults file. * * Parameters: * * thread_count * * Number of threads the engine will support. Pass 0 for default of 4. * * debug_flags * * Bitwise OR of flags indicating how debug output should (or should * not) be output. Pass 0 for default of no debugging. * * Returns 0 on success, -1 on error. On error errno will be set to * indicate error. Possible errnos are ENOMEM if memory cannot be * allocated. */ int ipmiconsole_engine_init (unsigned int thread_count, unsigned int debug_flags); /* * ipmiconsole_engine_submit * * Submit a context to the ipmiconsole engine non-blocking. This * function can return prior to a SOL session being established. A * return value of 0 indicates the context was submitted properly. A * return value of -1 indicates an error occurred during the * submission. On an error, ipmiconsole_ctx_errnum() can be used to * determine the type of error that occured. * * After a context has been submitted, the user may determine if a SOL * session has been established several ways: * * A) Poll on the context status, retrieved via * ipmiconsole_ctx_status(). On an error, ipmiconsole_ctx_errnum() * can be used to determine the specific IPMI related error that * occurred. * * B) Poll on the context file descriptor, retrieved via * ipmiconsole_ctx_fd(). A SOL establishment error will result in an * EOF being returned on the file descriptor. A proper SOL * establishment can be determined via a readable character on the * file descriptor. The use of the OUTPUT_ON_SOL_ESTABLISHED Engine * flag above can aid in this. The CLOSE_FD Engine flag can be set to * slightly alter this behavior, please see above. On an error, * ipmiconsole_ctx_errnum() can be used to determine the specific IPMI * related error that occurred. * * C) Specify a callback function. The callback function specified as * a parameter below will be called directly after a SOL session has * been established or a session establishment error has occurred * (e.g. SOL not supported, authentication error, etc.). Within those * callback functions, ipmiconsole_ctx_status() can be used to * determine which has occurred. This callback will be called by the * engine thread, therefore users may need to protect their * application's shared data. * * Due to the non-blocking semantics of this function, it is possible * that multiple errors could occur simultaneously and the errnum * retrieved via ipmiconsole_ctx_errnum() may not be the one that * caused the SOL session to fail. However, this will not occur given * proper usage of the API. For example, if the user called * ipmiconsole_engine_submit() twice with the same context, an SOL * error in the engine background could race with the setting of the * errnum IPMICONSOLE_ERR_CTX_IS_SUBMITTED in the second call. * * Parameters: * * callback * * If specified, a callback function will be called from the engine * when a SOL session has been established or a SOL establishment * error has occurred. Will only be called under a non-blocking * engine submission via ipmiconsole_engine_submit(). Will be * called once and only once during an individual engine submission. * For example, if a SOL session is established then a later session * timeout occurs, the later session timeout will not generate a * function call to the callback. Pass NULL for no callback. * * The callback function can be called simultaneously from different * engine threads. It is the user's responsibility to protect * against any race conditions in their callback function. * * callback_arg * * Specify an arbitrary argument to be passed to the callback * routine. If the callback will be required to process the context * status, the context should be included in this argument. * * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be * called to determine the cause of the error. */ int ipmiconsole_engine_submit (ipmiconsole_ctx_t c, Ipmiconsole_callback callback, void *callback_arg); /* * ipmiconsole_engine_submit_block * * Submit a context to the ipmiconsole engine and block until a SOL * session is established or an error/timeout occurs. A return value * of 0 indicates the SOL session was established and a -1 indicates * an error occurred. On an error, ipmiconsole_ctx_errnum() can be * used to determine the type of error that occured. * * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be * called to determine the cause of the error. */ int ipmiconsole_engine_submit_block (ipmiconsole_ctx_t c); /* * ipmiconsole_engine_teardown * * Teardown the ipmiconsole engine. This function will destroy * all threads and contexts managed by the engine. * * Parameters: * * cleanup_sol_sessions * * If set to non zero, SOL sessions will be torn down cleanly. * ipmiconsole_engine_teardown() will block until all active ipmi * sessions have been closed cleanly or timed out. */ void ipmiconsole_engine_teardown (int cleanup_sol_sessions); /* * ipmiconsole_ctx_create * * Create an ipmiconsole context. The context can then be submitted * into the ipmiconsole engine (via ipmiconsole_engine_submit() or * ipmiconsole_engine_submit_block()) to establish a SOL session. The * context cannot be submitted to the ipmiconsole engine more than * once. After it has been submitted to the ipmiconsole engine, it * cannot be reused. * * Parameters: * * hostname * * Host or IP address you wish to connect to. * * ipmi_config * * IPMI configuration. See ipmiconsole_ipmi_config definition * above. * * protocol_config * * IPMI protocol configuration. See ipmiconsole_protocol_config * definition above. * * engine_config * * Ipmiconsole engine configuration. See ipmiconsole_engine_config * definition above. * * Returns ctx on success, NULL on error. On error errno will be set to * indicate error. Possible errnos are EINVAL on invalid input, * ENOMEM if memory cannot be allocated, EMFILE if process file * descriptors limits have been reached, and EAGAIN if * ipmiconsole_engine_init() has not yet been called. */ ipmiconsole_ctx_t ipmiconsole_ctx_create (const char *hostname, struct ipmiconsole_ipmi_config *ipmi_config, struct ipmiconsole_protocol_config *protocol_config, struct ipmiconsole_engine_config *engine_config); /* * ipmiconsole_ctx_set_config * * Set the value of an advanced configuration value. This * configuration value must be set prior to a context being submitted * to the ipmiconsole engine (via ipmiconsole_engine_submit() or * ipmiconsole_engine_submit_block()). After it has been submitted to * the ipmiconsole engine, it cannot be changed. * * See enum ipmiconsole_ctx_config_option above for config options and * pointer types expected by this function. * * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be * called to determine the cause of the error. */ int ipmiconsole_ctx_set_config (ipmiconsole_ctx_t c, ipmiconsole_ctx_config_option_t config_option, void *config_option_value); /* * ipmiconsole_ctx_get_config * * Get the value of an advanced configuration value. * * See enum ipmiconsole_ctx_config_option above for config options and * pointer types expected by this function. * * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be * called to determine the cause of the error. */ int ipmiconsole_ctx_get_config (ipmiconsole_ctx_t c, ipmiconsole_ctx_config_option_t config_option, void *config_option_value); /* * ipmiconsole_ctx_errnum * * Returns the errnum of the most recently recorded error for the * context that has not yet been read by the user. */ int ipmiconsole_ctx_errnum (ipmiconsole_ctx_t c); /* * ipmiconsole_ctx_strerror * * Returns a pointer to statically allocated string describing the * error code in errnum. */ char *ipmiconsole_ctx_strerror (int errnum); /* * ipmiconsole_ctx_errormsg * * Returns a pointer to statically allocated string describing the * most recent error for the context. */ char *ipmiconsole_ctx_errormsg (ipmiconsole_ctx_t c); /* * ipmiconsole_ctx_status * * Returns the current context status. Primarily used to determine if * a context submission (submitted non-blocking via * ipmiconsole_engine_submit()) has been established or not. Returns * IPMICONSOLE_CTX_STATUS_ERROR (-1) on error. */ ipmiconsole_ctx_status_t ipmiconsole_ctx_status (ipmiconsole_ctx_t c); /* * ipmiconsole_ctx_fd * * Returns a file descriptor for console reading and writing after it * has been submitted to the engine. Returns -1 on error. * ipmiconsole_ctx_errnum() can be called to determine the cause of * the error. * * If the user closes the file descriptor while the serial over lan * session is established, the session will be torn down in the * engine. * * If an error occurs on the engine side (for example a session * timeout) the other end of the file descriptor pair (from which this * fd is a part of) will be closed. The error can be determined via * ipmiconsole_ctx_errnum(). The user of this file descriptor will * typically see this affect via an EOF on a read() or an EPIPE on a * write(). For alternate file descriptor behavior, see ENGINE flags * above. */ int ipmiconsole_ctx_fd (ipmiconsole_ctx_t c); /* * ipmiconsole_ctx_generate_break * * Generate a break on an active serial over LAN session. * * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be * called to determine the cause of the error. */ int ipmiconsole_ctx_generate_break (ipmiconsole_ctx_t c); /* * ipmiconsole_ctx_destroy * * Destroy a context. Will close file descriptor retrieved from * ipmiconsole_ctx_fd(). */ void ipmiconsole_ctx_destroy (ipmiconsole_ctx_t c); /* * ipmiconsole_username_is_valid * * Convenience function to determine if a username is valid. Note that * a NULL pointer, which would result in libipmiconsole using a * default value, is considered an invalid input here. * * Returns 1 if username is valid, 0 if it is not. */ int ipmiconsole_username_is_valid (const char *username); /* * ipmiconsole_password_is_valid * * Convenience function to determine if a password is valid. Note * that a NULL pointer, which would result in libipmiconsole using a * default value, is considered an invalid input here. * * Returns 1 if password is valid, 0 if it is not. */ int ipmiconsole_password_is_valid (const char *password); /* * ipmiconsole_k_g_is_valid * * Convenience function to determine if a k_g is valid. Note that a * NULL pointer, which would result in libipmiconsole using a default * value, is considered an invalid input here. * * Returns 1 if k_g is valid, 0 if it is not. */ int ipmiconsole_k_g_is_valid (const unsigned char *k_g, unsigned int k_g_len); /* * ipmiconsole_privilege_level_is_valid * * Convenience function to determine if a privilege level is valid. * Note that a negative value, which would result in libipmiconsole * using a default value, is considered an invalid input here. * * Returns 1 if privilege level is valid, 0 if it is not. */ int ipmiconsole_privilege_level_is_valid (int privilege_level); /* * ipmiconsole_cipher_suite_id_is_valid * * Convenience function to determine if a cipher suite id is valid. * Note that a negative value, which would result in libipmiconsole * using a default value, is considered an invalid input here. * * Returns 1 if cipher suite id is valid, 0 if it is not. */ int ipmiconsole_cipher_suite_id_is_valid (int cipher_suite_id); /* * ipmiconsole_workaround_flags_is_valid * * Convenience function to determine if workaround flags are valid. * Note that a bitmask value of IPMICONSOLE_WORKAROUND_DEFAULT, which * would result in libipmiconsole using a default value, is considered * an invalid input here. * * Returns 1 if workaround flags are valid, 0 if they are not. */ int ipmiconsole_workaround_flags_is_valid (unsigned int workaround_flags); #ifdef __cplusplus } #endif #endif /* IPMICONSOLE_H */