/*****************************************************************************\
* $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 <chu11@llnl.gov>
* 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 <http://www.gnu.org/licenses/>.
\*****************************************************************************/
#ifndef IPMICONSOLE_H
#define IPMICONSOLE_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include <freeipmi/freeipmi.h>
/*
* 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 */