1/*****************************************************************************\ 2 * $Id: ipmiconsole.h,v 1.89 2010-08-03 00:10:59 chu11 Exp $ 3 ***************************************************************************** 4 * Copyright (C) 2007-2015 Lawrence Livermore National Security, LLC. 5 * Copyright (C) 2006-2007 The Regents of the University of California. 6 * Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). 7 * Written by Albert Chu <chu11@llnl.gov> 8 * UCRL-CODE-221226 9 * 10 * This file is part of Ipmiconsole, a set of IPMI 2.0 SOL libraries 11 * and utilities. For details, see http://www.llnl.gov/linux/. 12 * 13 * Ipmiconsole is free software; you can redistribute it and/or modify 14 * it under the terms of the GNU General Public License as published by the 15 * Free Software Foundation; either version 3 of the License, or (at your 16 * option) any later version. 17 * 18 * Ipmiconsole is distributed in the hope that it will be useful, but 19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 21 * for more details. 22 * 23 * You should have received a copy of the GNU General Public License along 24 * with Ipmiconsole. If not, see <http://www.gnu.org/licenses/>. 25\*****************************************************************************/ 26 27#ifndef IPMICONSOLE_H 28#define IPMICONSOLE_H 29 30#ifdef __cplusplus 31extern "C" { 32#endif 33 34#include <stdint.h> 35#include <freeipmi/freeipmi.h> 36 37/* 38 * Libipmiconsole version 39 * 40 * MAJOR - Incremented when interfaces are changed or removed. 41 * Interfaces may be binary incompatible. When incremented, MINOR 42 * and PATCH are zeroed. 43 * 44 * MINOR - Incremented when interfaces are added. Interfaces are 45 * binary compatible with older minor versions. When incremented, 46 * PATCH is zeroed. 47 * 48 * PATCH - Incremented when interfaces are not changed. Typically 49 * incremented due to bug fixes or minor features. Interfaces are 50 * forward and backward compatible to other PATCH versions. 51 */ 52 53#define LIBIPMICONSOLE_VERSION_MAJOR @LIBIPMICONSOLE_VERSION_MAJOR@ 54#define LIBIPMICONSOLE_VERSION_MINOR @LIBIPMICONSOLE_VERSION_MINOR@ 55#define LIBIPMICONSOLE_VERSION_PATCH @LIBIPMICONSOLE_VERSION_PATCH@ 56 57/* 58 * IPMI Console Error Codes 59 */ 60#define IPMICONSOLE_ERR_SUCCESS 0 61#define IPMICONSOLE_ERR_CTX_NULL 1 62#define IPMICONSOLE_ERR_CTX_INVALID 2 63#define IPMICONSOLE_ERR_ALREADY_SETUP 3 64#define IPMICONSOLE_ERR_NOT_SETUP 4 65#define IPMICONSOLE_ERR_CTX_NOT_SUBMITTED 5 66#define IPMICONSOLE_ERR_CTX_IS_SUBMITTED 6 67#define IPMICONSOLE_ERR_PARAMETERS 7 68#define IPMICONSOLE_ERR_HOSTNAME_INVALID 8 69#define IPMICONSOLE_ERR_IPMI_2_0_UNAVAILABLE 9 70#define IPMICONSOLE_ERR_CIPHER_SUITE_ID_UNAVAILABLE 10 71#define IPMICONSOLE_ERR_USERNAME_INVALID 11 72#define IPMICONSOLE_ERR_PASSWORD_INVALID 12 73#define IPMICONSOLE_ERR_K_G_INVALID 13 74#define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_INSUFFICIENT 14 75#define IPMICONSOLE_ERR_PRIVILEGE_LEVEL_CANNOT_BE_OBTAINED 15 76#define IPMICONSOLE_ERR_SOL_UNAVAILABLE 16 77#define IPMICONSOLE_ERR_SOL_INUSE 17 78#define IPMICONSOLE_ERR_SOL_STOLEN 18 79#define IPMICONSOLE_ERR_SOL_REQUIRES_ENCRYPTION 19 80#define IPMICONSOLE_ERR_SOL_REQUIRES_NO_ENCRYPTION 20 81#define IPMICONSOLE_ERR_BMC_BUSY 21 82#define IPMICONSOLE_ERR_BMC_ERROR 22 83#define IPMICONSOLE_ERR_BMC_IMPLEMENTATION 23 84#define IPMICONSOLE_ERR_CONNECTION_TIMEOUT 24 85#define IPMICONSOLE_ERR_SESSION_TIMEOUT 25 86#define IPMICONSOLE_ERR_EXCESS_RETRANSMISSIONS_SENT 26 87#define IPMICONSOLE_ERR_EXCESS_ERRORS_RECEIVED 27 88#define IPMICONSOLE_ERR_OUT_OF_MEMORY 28 89#define IPMICONSOLE_ERR_TOO_MANY_OPEN_FILES 29 90#define IPMICONSOLE_ERR_SYSTEM_ERROR 30 91#define IPMICONSOLE_ERR_INTERNAL_ERROR 31 92#define IPMICONSOLE_ERR_ERRNUMRANGE 32 93 94/* 95 * Debug Flags 96 * 97 * Utilized with ipmiconsole_engine_init() or with struct 98 * ipmiconsole_engine_config below for debugging. 99 * 100 * When used with ipmiconsole_engine_init(), enables debugging in 101 * libipmiconsole global activities, such as the libipmiconsole engine 102 * threads. 103 * 104 * When used with struct ipmiconsole_engine_config and a context, 105 * enables debugging specific to an IPMI connection with a specific 106 * host. 107 * 108 * STDOUT - Output debugging to stdout 109 * STDERR - Output debugging to stderr 110 * SYSLOG - Output debugging to the Syslog 111 * FILE - Output debugging to files in current working directory 112 * IPMI_PACKETS - Dump IPMI Packets too 113 * DEFAULT - Informs library to use default, may it be the internal default 114 * or an alternate default configured via libipmiconsole.conf. 115 */ 116#define IPMICONSOLE_DEBUG_STDOUT 0x00000001 117#define IPMICONSOLE_DEBUG_STDERR 0x00000002 118#define IPMICONSOLE_DEBUG_SYSLOG 0x00000004 119#define IPMICONSOLE_DEBUG_FILE 0x00000008 120#define IPMICONSOLE_DEBUG_IPMI_PACKETS 0x00000010 121#define IPMICONSOLE_DEBUG_DEFAULT 0xFFFFFFFF 122 123/* 124 * IPMI Privilege Constants 125 * 126 * Utilized with struct ipmiconsole_ipmi_config below to specify a 127 * privilege level to authenticate with. 128 */ 129#define IPMICONSOLE_PRIVILEGE_USER 0 130#define IPMICONSOLE_PRIVILEGE_OPERATOR 1 131#define IPMICONSOLE_PRIVILEGE_ADMIN 2 132 133/* 134 * Workaround Flags 135 * 136 * Utilized with struct ipmiconsole_ipmi_config below to specify 137 * workarounds for specific motherboard manufacturers. 138 * 139 * AUTHENTICATION_CAPABILITIES 140 * 141 * This workaround flag will skip early checks for username 142 * capabilities, authentication capabilities, and K_g support and 143 * allow IPMI authentication to succeed. It works around multiple 144 * issues in which the remote system does not properly report username 145 * capabilities, authentication capabilities, or K_g status. 146 * 147 * INTEL_2_0_SESSION 148 * 149 * This workaround flag will work around several Intel IPMI 2.0 150 * authentication issues. The issues covered include padding of 151 * usernames, automatic acceptance of a RAKP 4 response integrity 152 * check when using the integrity algorithm MD5-128, and password 153 * truncation if the authentication algorithm is HMAC-MD5-128. 154 * 155 * SUPERMICRO_2_0_SESSION 156 * 157 * This workaround option will work around several Supermicro IPMI 2.0 158 * authentication issues on motherboards w/ Peppercon IPMI firmware. 159 * The issues covered include handling invalid length authentication 160 * codes. 161 * 162 * SUN_2_0_SESSION 163 * 164 * This workaround flag will work work around several Sun IPMI 2.0 165 * authentication issues. The issues covered include invalid lengthed 166 * hash keys, improperly hashed keys, and invalid cipher suite 167 * records. This workaround automatically includes the 168 * OPEN_SESSION_PRIVILEGE workaround. 169 * 170 * OPEN_SESSION_PRIVILEGE 171 * 172 * This workaround flag will slightly alter FreeIPMI's IPMI 2.0 173 * connection protocol to workaround an invalid hashing algorithm used 174 * by the remote system. The privilege level sent during the Open 175 * Session stage of an IPMI 2.0 connection is used for hashing keys 176 * instead of the privilege level sent during the RAKP1 connection 177 * stage. This workaround is automatically triggered with the 178 * SUN_2_0_SESSION workaround. 179 * 180 * NON_EMPTY_INTEGRITY_CHECK_VALUE 181 * 182 * This workaround option will work around an invalid integrity check 183 * value during an IPMI 2.0 session establishment when using Cipher 184 * Suite ID 0. The integrity check value should be 0 length, however 185 * the remote motherboard responds with a non-empty field. 186 * 187 * NO_CHECKSUM_CHECK 188 * 189 * This workaround option will work around motheboards that calculate 190 * checksums incorrectly in IPMI command responses, but the packet is 191 * otherwise valid. Users are cautioned on the use of this option, as 192 * it removes some validation of packet integrity. However, it is 193 * unlikely to be an issue in most situations. 194 * 195 * SERIAL_ALERTS_DEFERRED 196 * 197 * This workaround option will set serial alerts to be deferred 198 * instead of have them be failures. This works around motherboards 199 * that perform IPMI over serial along with IPMI serial over LAN. 200 * 201 * INCREMENT_SOL_PACKET_SEQUENCE 202 * 203 * This workaround option will increment the SOL payload packet 204 * sequence number under dire circumstances. Normally SOL should 205 * never do this, however some motherboards have shown to get "stuck" 206 * due to an internal bug on the motherboard. This workaround can 207 * help in getting the BMC un-stuck. 208 * 209 * IGNORE_SOL_PAYLOAD_SIZE 210 * 211 * This workaround flag will not check for valid SOL payload sizes and 212 * assume a proper set. It works around remote systems that report 213 * invalid IPMI 2.0 SOL payload sizes. 214 * 215 * IGNORE_SOL_PORT 216 * 217 * This workaround flag will ignore alternate SOL ports specified 218 * during the protocol. It works around remote systems that report 219 * invalid alternate SOL ports. 220 * 221 * SKIP_SOL_ACTIVATION_STATUS 222 * 223 * This workaround flag will not check the current activation status 224 * of SOL during the protocol setup. It works around remote systems 225 * that do not properly support this command. 226 * 227 * SKIP_CHANNEL_PAYLOAD_SUPPORT 228 * 229 * This workaround flag will skip the portion of the protocol that 230 * checks if SOL is supported on the current channel. It works around 231 * remote systems that do not properly support this command. 232 * 233 * DEFAULT 234 * 235 * Informs library to use default, may it be the internal default or 236 * an alternate default configured via libipmiconsole.conf. 237 * 238 * Note: The non-logical bitmask order below is set for future 239 * expansion and matching w/ libfreeipmi. 240 */ 241#define IPMICONSOLE_WORKAROUND_AUTHENTICATION_CAPABILITIES 0x00000001 242#define IPMICONSOLE_WORKAROUND_INTEL_2_0_SESSION 0x00000002 243#define IPMICONSOLE_WORKAROUND_SUPERMICRO_2_0_SESSION 0x00000004 244#define IPMICONSOLE_WORKAROUND_SUN_2_0_SESSION 0x00000008 245#define IPMICONSOLE_WORKAROUND_OPEN_SESSION_PRIVILEGE 0x00000010 246#define IPMICONSOLE_WORKAROUND_NON_EMPTY_INTEGRITY_CHECK_VALUE 0x00000020 247#define IPMICONSOLE_WORKAROUND_NO_CHECKSUM_CHECK 0x00000040 248#define IPMICONSOLE_WORKAROUND_SERIAL_ALERTS_DEFERRED 0x00000080 249#define IPMICONSOLE_WORKAROUND_INCREMENT_SOL_PACKET_SEQUENCE 0x00000100 250#define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PAYLOAD_SIZE 0x01000000 251#define IPMICONSOLE_WORKAROUND_IGNORE_SOL_PORT 0x02000000 252#define IPMICONSOLE_WORKAROUND_SKIP_SOL_ACTIVATION_STATUS 0x04000000 253#define IPMICONSOLE_WORKAROUND_SKIP_CHANNEL_PAYLOAD_SUPPORT 0x08000000 254#define IPMICONSOLE_WORKAROUND_DEFAULT 0xFFFFFFFF 255 256/* 257 * Engine Flags 258 * 259 * Utilized with struct ipmiconsole_engine_config below to alter 260 * libipmiconsole engine behavior. 261 * 262 * CLOSE_FD 263 * 264 * By default, the ipmiconsole engine will not close the file 265 * descriptor (returned by ipmiconsole_ctx_fd()) within the 266 * ipmiconsole engine (such as a session timeout). On errors (such as 267 * session timeout), a user will subsequently see an EOF on a read() 268 * or an EPIPE on a write() to know an error occurred. 269 * 270 * This flag will inform the engine to close the file descriptor for 271 * the user. This will change the behavior of how the user should 272 * program with the file descriptor. For example, calls to read() and 273 * write() would likely return with EBADF errors instead of EOF or 274 * EPIPE errors respectively. Calls to select() may return with EBADF 275 * errors and calls to poll() could result in POLLNVAL returned 276 * events. 277 * 278 * OUTPUT_ON_SOL_ESTABLISHED 279 * 280 * When submitting a context to the engine non-blocking, another way 281 * to determine if the SOL session has been established is if data has 282 * output from the remote console and is available for you to read. 283 * Under most circumstances, this isn't a controllable situation. 284 * 285 * This flag will inform the engine to output a single NUL character 286 * ('\0') to the console once a SOL session has been established. If 287 * the CLOSE_FD flag isn't used above, this would allow the user to 288 * expect an EOF vs. 1 byte of data on a read() to determine if the 289 * SOL session has failed or succeeded. The user may choose to output 290 * the NUL anyways (it should do no harm) or simply throw out the 291 * first byte ever read from remote console. 292 * 293 * LOCK_MEMORY 294 * 295 * Inform libipmiconsole to lock memory to prevent sensitive 296 * information (such as usernames and passwords) to be non-swappable. 297 * 298 * SERIAL_KEEPALIVE 299 * 300 * On some motherboards, it's been observed that IPMI connections 301 * between the IPMI client and remote BMC/server can stay alive while 302 * the remote server's internal connection between the BMC and serial 303 * chip can be lost. This has been observed under several situations, 304 * such as when the remote system is rebooted or a IPMI SOL session is 305 * stolen. 306 * 307 * The affect is that this loss of the serial connection will not be 308 * noticed by the IPMI client until serial data is transfered from the 309 * client to the BMC and a timeout (or similar error) eventually occurs. 310 * The IPMI client must then reconnect to restablish the session. 311 * 312 * This is a severe problem for IPMI clients that predominantly log 313 * serial data or display serial output without user interactivity. 314 * From the IPMI client perspective, there is simply no output from 315 * the serial port and no error has actually occurred. 316 * 317 * This option will inform the libipmiconsole engine to send serial 318 * keepalive packets in addition to the IPMI keepalive packets that 319 * normally keep a connection alive. The serial keepalive packets are 320 * standard SOL payload packets, but contain a single NUL character in 321 * them. The single NUL character is to ensure that the underlying 322 * serial receiver is alive and functioning. Retransmission and 323 * timeouts are handled identically to normal IPMI packets in the code 324 * (e.g. as if somebody typed a character). The serial keepalive 325 * packets are dispatched if a SOL packet response has not been 326 * received within the length of time of a session timeout. 327 * 328 * This option is highly recommended for IPMI clients that do not have 329 * high user interactivity, as this may discover broken connections 330 * far more quickly. However, caution should be maintained, as the 331 * NUL character byte may affect the remote system depending on what 332 * input it may or may not be expecting. 333 * 334 * SERIAL_KEEPALIVE_EMPTY 335 * 336 * This option is identical to SERIAL_KEEPALIVE, except that the 337 * serial keepalive packets are empty and without character data. On 338 * some motherboards, this may be sufficient to deal with the "serial 339 * keepalive" issue and character data need not be sent with each 340 * packet. On some systems though, a SOL packet without character 341 * data may not be ACKed, and therefore the keepalive fails. 342 * 343 * DEFAULT 344 * 345 * Informs library to use default, may it be the internal default or 346 * an alternate default configured via libipmiconsole.conf. 347 */ 348#define IPMICONSOLE_ENGINE_CLOSE_FD 0x00000001 349#define IPMICONSOLE_ENGINE_OUTPUT_ON_SOL_ESTABLISHED 0x00000002 350#define IPMICONSOLE_ENGINE_LOCK_MEMORY 0x00000004 351#define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE 0x00000008 352#define IPMICONSOLE_ENGINE_SERIAL_KEEPALIVE_EMPTY 0x00000010 353#define IPMICONSOLE_ENGINE_DEFAULT 0xFFFFFFFF 354 355/* 356 * Behavior Flags 357 * 358 * Utilized with struct ipmiconsole_protocol_config below to atler 359 * SOL connection behavior. 360 * 361 * ERROR_ON_SOL_INUSE 362 * 363 * Under most circumstances, if SOL is detected as being in use, 364 * libipmiconsole will attempt to deactivate the earlier SOL session 365 * and activate the SOL session under the current one. This default 366 * behavior exists for several reasons, most notably that earlier SOL 367 * sessions may have not been able to be deactivated properly. This 368 * security flag changes the default behavior to return an error if 369 * SOL is already detected as being in use. If it is detected as in 370 * use, the errnum returned from ipmiconsole_ctx_errnum() would be 371 * IPMICONSOLE_ERR_SOL_INUSE. 372 * 373 * DEACTIVATE_ONLY 374 * 375 * Only attempt to deactivate the SOL session. If an SOL session is 376 * not active, do nothing. 377 * 378 * DEACTIVATE_ALL_INSTANCES 379 * 380 * When a SOL session is deactivated via the DEACTIVATE_ONLY flag, 381 * only the currently configured SOL payload instance will be 382 * deactivated, not any other instance. This flag will inform 383 * libipmiconsole to deactivate all presently activated instances. 384 * This may be useful in a few circumstances where a user might want 385 * to deactivate all current sessions. 386 * 387 * DEFAULT 388 * 389 * Informs library to use default, may it be the internal default or 390 * an alternate default configured via libipmiconsole.conf. 391 */ 392#define IPMICONSOLE_BEHAVIOR_ERROR_ON_SOL_INUSE 0x00000001 393#define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ONLY 0x00000002 394#define IPMICONSOLE_BEHAVIOR_DEACTIVATE_ALL_INSTANCES 0x00000004 395#define IPMICONSOLE_BEHAVIOR_DEFAULT 0xFFFFFFFF 396 397/* 398 * Context Status 399 * 400 * Returned by ipmiconsole_ctx_status() below. 401 * 402 * ERROR 403 * 404 * An error has occurred retrieving the status. 405 * 406 * NOT_SUBMITTED 407 * 408 * The context has not been submitted to the engine. 409 * 410 * SUBMITTED 411 * 412 * The context has been submitted to the engine. SOL has not been 413 * established and an error has not yet occurred. 414 * 415 * SOL_ERROR 416 * 417 * The context has received an error during SOL establishment. 418 * 419 * SOL_ESTABLISHED 420 * 421 * The context has established a SOL session. 422 * 423 */ 424enum ipmiconsole_ctx_status 425{ 426 IPMICONSOLE_CTX_STATUS_ERROR = -1, 427 IPMICONSOLE_CTX_STATUS_NOT_SUBMITTED = 0, 428 IPMICONSOLE_CTX_STATUS_SUBMITTED = 1, 429 IPMICONSOLE_CTX_STATUS_SOL_ERROR = 2, 430 IPMICONSOLE_CTX_STATUS_SOL_ESTABLISHED = 3, 431}; 432typedef enum ipmiconsole_ctx_status ipmiconsole_ctx_status_t; 433 434/* 435 * ipmiconsole_ipmi_config 436 * 437 * IPMI configuration for a connection to a remote IPMI machine. 438 * Defaults can be modified using the libipmiconsole.conf file. 439 * 440 * username 441 * 442 * BMC username. Pass NULL ptr for default username of null 443 * (e.g. empty) username or the configured value in 444 * libipmiconsole.conf. Maximum length of 16 bytes. 445 * 446 * password 447 * 448 * BMC password. Pass NULL ptr for default of null (e.g. empty) 449 * password or the configured value in libipmiconsole.conf. Maximum 450 * length of 20 bytes. 451 * 452 * k_g 453 * 454 * BMC Key for 2-key authentication. Pass NULL ptr to use the 455 * default of null (e.g. empty) k_g or the configured value in 456 * libipmiconsole.conf. The null/empty k_g key equates to using the 457 * password as the BMC key. The k_g key need not be an ascii 458 * string. 459 * 460 * k_g_len 461 * 462 * Length of k_g. Necessary b/c k_g may contain null values in its 463 * key. Maximum length of 20 bytes. 464 * 465 * privilege_level 466 * 467 * privilege level to authenticate with. 468 * 469 * Supported privilege levels: 470 * 471 * IPMICONSOLE_PRIVILEGE_USER 472 * IPMICONSOLE_PRIVILEGE_OPERATOR 473 * IPMICONSOLE_PRIVILEGE_ADMIN 474 * 475 * Pass < 0 for default of IPMICONSOLE_PRIVILEGE_ADMIN or the 476 * configured value in libipmiconsole.conf 477 * 478 * cipher_suite_id 479 * 480 * Cipher suite identifier to determine authentication, integrity, 481 * and confidentiality algorithms to use. 482 * 483 * Supported Cipher Suite IDs 484 * (Key: A - Authentication Algorithm 485 * I - Integrity Algorithm 486 * C - Confidentiality Algorithm) 487 * 488 * 0 - A = None; I = None; C = None 489 * 1 - A = HMAC-SHA1; I = None; C = None 490 * 2 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = None 491 * 3 - A = HMAC-SHA1; I = HMAC-SHA1-96; C = AES-CBC-128 492 * 6 - A = HMAC-MD5; I = None; C = None 493 * 7 - A = HMAC-MD5; I = HMAC-MD5-128; C = None 494 * 8 - A = HMAC-MD5; I = HMAC-MD5-128; C = AES-CBC-128 495 * 11 - A = HMAC-MD5; I = MD5-128; C = None 496 * 12 - A = HMAC-MD5; I = MD5-128; C = AES-CBC-128 497 * 15 - A = HMAC-SHA256; I = None; C = None 498 * 16 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = None 499 * 17 - A = HMAC-SHA256; I = HMAC-SHA256-128; C = AES-CBC-128 500 * 501 * Pass < 0 for default of 3 or the configured value in 502 * libipmiconsole.conf 503 * 504 * workaround_flags 505 * 506 * Bitwise OR of flags indicating IPMI implementation changes. Some 507 * BMCs which are non-compliant and may require a workaround flag 508 * for correct operation. Pass IPMICONSOLE_WORKAROUND_DEFAULT for 509 * default of 0 (i.e. no modifications to the IPMI protocol) or the 510 * configured value in libipmiconsole.conf 511 */ 512struct ipmiconsole_ipmi_config 513{ 514 char *username; 515 char *password; 516 unsigned char *k_g; 517 unsigned int k_g_len; 518 int privilege_level; 519 int cipher_suite_id; 520 unsigned int workaround_flags; 521}; 522 523/* 524 * ipmiconsole_protocol_config 525 * 526 * Configuration information for the IPMI protocol management. 527 * Defaults can be modified using the libipmiconsole.conf file. 528 * 529 * session_timeout_len 530 * 531 * Specifies the session timeout length in milliseconds. Pass <= 0 532 * for default of 60000 (60 seconds) or the configured value in 533 * libipmiconsole.conf. 534 * 535 * retransmission_timeout_len 536 * 537 * Specifies the packet retransmission timeout length in 538 * milliseconds. Pass <= 0 for default of 500 (0.5 seconds) or the 539 * configured value in libipmiconsole.conf. 540 * 541 * retransmission_backoff_count 542 * 543 * Specifies the packet retransmission count until retransmission 544 * timeout lengths will be backed off. Pass <= 0 for default of 2 545 * or the configured value in libipmiconsole.conf. 546 * 547 * keepalive_timeout_len 548 * 549 * Specifies the session timeout length in milliseconds until a 550 * keepalive packet is sent. Pass <= 0 for default of 20000 (20 551 * seconds) or the configured value in libipmiconsole.conf. 552 * 553 * retransmission_keepalive_timeout_len 554 * 555 * Specifies the keepalive packet retransmission timeout length in 556 * milliseconds. Pass <= 0 for default of 5000 (5 seconds) or the 557 * configured value in libipmiconsole.conf. 558 * 559 * acceptable_packet_errors_count 560 * 561 * Specifies the maximum number of consecutive packet errors that 562 * can be received from a remote BMC before an error is returned and 563 * the session ended. Pass <= 0 for default of 16 or the configured 564 * value in libipmiconsole.conf. 565 * 566 * Note: This has been added to the behavior of the IPMI engine due 567 * to issues where remote BMCs can become "un-synced" with sequence 568 * numbers due to a network kernel boot. It is possible a stream of 569 * packets can be sent to the remote client with session sequence 570 * numbers that are excessively outside of the acceptable window 571 * range. 572 * 573 * maximum_retransmission_count 574 * 575 * Specifies the maximum number of retransmissions that can be sent 576 * for any IPMI packet before an error is returned and the session 577 * ended. Pass <= 0 for default of 16 or the configured value in 578 * libipmiconsole.conf. 579 * 580 * Note: This has been added to the behavior of the IPMI engine due 581 * to issues where remote BMCs can become "un-synced" with sequence 582 * numbers due to a network kernel boot. It is possible for some 583 * packets (in particular 'ping' packets to keep an IPMI session 584 * alive) to be accepted by the remote BMC, but not SOL packets. 585 * 586 */ 587struct ipmiconsole_protocol_config 588{ 589 int session_timeout_len; 590 int retransmission_timeout_len; 591 int retransmission_backoff_count; 592 int keepalive_timeout_len; 593 int retransmission_keepalive_timeout_len; 594 int acceptable_packet_errors_count; 595 int maximum_retransmission_count; 596}; 597 598/* 599 * ipmiconsole_engine_config 600 * 601 * Configuration information for how the engine should interact with 602 * the user or API. Defaults can be modified using the 603 * libipmiconsole.conf file. 604 * 605 * engine_flags 606 * 607 * Bitwise OR of flags indicating how the ipmiconsole engine should 608 * behave for a particular context. Pass IPMICONSOLE_ENGINE_DEFAULT 609 * for default of 0 or the configured value in libipmiconsole.conf. 610 * 611 * behavior_flags 612 * 613 * Bitwise OR of flags indicating any protocol behavior that should 614 * be changed from the default. Pass IPMICONSOLE_BEHAVIOR_DEFAULT 615 * for default of 0 or the configured value in libipmiconsole.conf. 616 * 617 * debug_flags 618 * 619 * Bitwise OR of flags indicating how debug output should (or should 620 * not) be output. Pass IPMICONSOLE_DEBUG_DEFAULT for default of 0 621 * or the configured value in libipmiconsole.conf. 622 * 623 */ 624struct ipmiconsole_engine_config 625{ 626 unsigned int engine_flags; 627 unsigned int behavior_flags; 628 unsigned int debug_flags; 629}; 630 631/* 632 * Context Config Option 633 * 634 * Used for setting or getting advanced configuration options. See 635 * ipmiconsole_ctx_set_config_option() and 636 * ipmiconsole_ctx_get_config_option(). 637 * 638 * SOL_PAYLOAD_INSTANCE 639 * 640 * The SOL payload instance number to be used. Defaults to 1 and has 641 * range of 1 to 15. Most systems only support a single instance, 642 * however a few allow users to access multiple. They could be used 643 * to allow multiple users to see the same serial session, or allow 644 * users to access different serial sessions behind a device. It is 645 * not commonly available or necessary when communicating via SOL to a 646 * single server. The SOL payload instance number is specified and 647 * retrieved via a pointer to an unsigned int. 648 * 649 */ 650enum ipmiconsole_ctx_config_option 651{ 652 IPMICONSOLE_CTX_CONFIG_OPTION_SOL_PAYLOAD_INSTANCE = 0, 653}; 654typedef enum ipmiconsole_ctx_config_option ipmiconsole_ctx_config_option_t; 655 656#define IPMICONSOLE_THREAD_COUNT_MAX 32 657 658typedef struct ipmiconsole_ctx *ipmiconsole_ctx_t; 659 660/* 661 * Ipmiconsole_callback 662 * 663 * Function prototype for a callback function. 664 * ipmiconsole_engine_submit() below. 665 */ 666typedef void (*Ipmiconsole_callback)(void *); 667 668/* 669 * ipmiconsole_engine_init 670 * 671 * Initialize the ipmiconsole engine. Engine threads will be created 672 * which will manage SOL sessions for the user. This function must be 673 * called before ipmi console contexts can be submitted into the 674 * engine. This call will also parse and load alternate defaults from 675 * the libipmiconsole.conf defaults file. 676 * 677 * Parameters: 678 * 679 * thread_count 680 * 681 * Number of threads the engine will support. Pass 0 for default of 4. 682 * 683 * debug_flags 684 * 685 * Bitwise OR of flags indicating how debug output should (or should 686 * not) be output. Pass 0 for default of no debugging. 687 * 688 * Returns 0 on success, -1 on error. On error errno will be set to 689 * indicate error. Possible errnos are ENOMEM if memory cannot be 690 * allocated. 691 */ 692int ipmiconsole_engine_init (unsigned int thread_count, 693 unsigned int debug_flags); 694 695/* 696 * ipmiconsole_engine_submit 697 * 698 * Submit a context to the ipmiconsole engine non-blocking. This 699 * function can return prior to a SOL session being established. A 700 * return value of 0 indicates the context was submitted properly. A 701 * return value of -1 indicates an error occurred during the 702 * submission. On an error, ipmiconsole_ctx_errnum() can be used to 703 * determine the type of error that occured. 704 * 705 * After a context has been submitted, the user may determine if a SOL 706 * session has been established several ways: 707 * 708 * A) Poll on the context status, retrieved via 709 * ipmiconsole_ctx_status(). On an error, ipmiconsole_ctx_errnum() 710 * can be used to determine the specific IPMI related error that 711 * occurred. 712 * 713 * B) Poll on the context file descriptor, retrieved via 714 * ipmiconsole_ctx_fd(). A SOL establishment error will result in an 715 * EOF being returned on the file descriptor. A proper SOL 716 * establishment can be determined via a readable character on the 717 * file descriptor. The use of the OUTPUT_ON_SOL_ESTABLISHED Engine 718 * flag above can aid in this. The CLOSE_FD Engine flag can be set to 719 * slightly alter this behavior, please see above. On an error, 720 * ipmiconsole_ctx_errnum() can be used to determine the specific IPMI 721 * related error that occurred. 722 * 723 * C) Specify a callback function. The callback function specified as 724 * a parameter below will be called directly after a SOL session has 725 * been established or a session establishment error has occurred 726 * (e.g. SOL not supported, authentication error, etc.). Within those 727 * callback functions, ipmiconsole_ctx_status() can be used to 728 * determine which has occurred. This callback will be called by the 729 * engine thread, therefore users may need to protect their 730 * application's shared data. 731 * 732 * Due to the non-blocking semantics of this function, it is possible 733 * that multiple errors could occur simultaneously and the errnum 734 * retrieved via ipmiconsole_ctx_errnum() may not be the one that 735 * caused the SOL session to fail. However, this will not occur given 736 * proper usage of the API. For example, if the user called 737 * ipmiconsole_engine_submit() twice with the same context, an SOL 738 * error in the engine background could race with the setting of the 739 * errnum IPMICONSOLE_ERR_CTX_IS_SUBMITTED in the second call. 740 * 741 * Parameters: 742 * 743 * callback 744 * 745 * If specified, a callback function will be called from the engine 746 * when a SOL session has been established or a SOL establishment 747 * error has occurred. Will only be called under a non-blocking 748 * engine submission via ipmiconsole_engine_submit(). Will be 749 * called once and only once during an individual engine submission. 750 * For example, if a SOL session is established then a later session 751 * timeout occurs, the later session timeout will not generate a 752 * function call to the callback. Pass NULL for no callback. 753 * 754 * The callback function can be called simultaneously from different 755 * engine threads. It is the user's responsibility to protect 756 * against any race conditions in their callback function. 757 * 758 * callback_arg 759 * 760 * Specify an arbitrary argument to be passed to the callback 761 * routine. If the callback will be required to process the context 762 * status, the context should be included in this argument. 763 * 764 * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be 765 * called to determine the cause of the error. 766 */ 767int ipmiconsole_engine_submit (ipmiconsole_ctx_t c, 768 Ipmiconsole_callback callback, 769 void *callback_arg); 770 771/* 772 * ipmiconsole_engine_submit_block 773 * 774 * Submit a context to the ipmiconsole engine and block until a SOL 775 * session is established or an error/timeout occurs. A return value 776 * of 0 indicates the SOL session was established and a -1 indicates 777 * an error occurred. On an error, ipmiconsole_ctx_errnum() can be 778 * used to determine the type of error that occured. 779 * 780 * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be 781 * called to determine the cause of the error. 782 */ 783int ipmiconsole_engine_submit_block (ipmiconsole_ctx_t c); 784 785/* 786 * ipmiconsole_engine_teardown 787 * 788 * Teardown the ipmiconsole engine. This function will destroy 789 * all threads managed by the engine. Users are still required to 790 * destroy remaining contexts with ipmiconsole_ctx_destroy(). 791 * 792 * Parameters: 793 * 794 * cleanup_sol_sessions 795 * 796 * If set to non zero, SOL sessions will be torn down cleanly. 797 * ipmiconsole_engine_teardown() will block until all active ipmi 798 * sessions have been closed cleanly or timed out. 799 */ 800void ipmiconsole_engine_teardown (int cleanup_sol_sessions); 801 802/* 803 * ipmiconsole_ctx_create 804 * 805 * Create an ipmiconsole context. The context can then be submitted 806 * into the ipmiconsole engine (via ipmiconsole_engine_submit() or 807 * ipmiconsole_engine_submit_block()) to establish a SOL session. The 808 * context cannot be submitted to the ipmiconsole engine more than 809 * once. After it has been submitted to the ipmiconsole engine, it 810 * cannot be reused. 811 * 812 * Parameters: 813 * 814 * hostname 815 * 816 * Host or IP address you wish to connect to. 817 * 818 * ipmi_config 819 * 820 * IPMI configuration. See ipmiconsole_ipmi_config definition 821 * above. 822 * 823 * protocol_config 824 * 825 * IPMI protocol configuration. See ipmiconsole_protocol_config 826 * definition above. 827 * 828 * engine_config 829 * 830 * Ipmiconsole engine configuration. See ipmiconsole_engine_config 831 * definition above. 832 * 833 * Returns ctx on success, NULL on error. On error errno will be set to 834 * indicate error. Possible errnos are EINVAL on invalid input, 835 * ENOMEM if memory cannot be allocated, EMFILE if process file 836 * descriptors limits have been reached, and EAGAIN if 837 * ipmiconsole_engine_init() has not yet been called. 838 */ 839ipmiconsole_ctx_t ipmiconsole_ctx_create (const char *hostname, 840 struct ipmiconsole_ipmi_config *ipmi_config, 841 struct ipmiconsole_protocol_config *protocol_config, 842 struct ipmiconsole_engine_config *engine_config); 843 844/* 845 * ipmiconsole_ctx_set_config 846 * 847 * Set the value of an advanced configuration value. This 848 * configuration value must be set prior to a context being submitted 849 * to the ipmiconsole engine (via ipmiconsole_engine_submit() or 850 * ipmiconsole_engine_submit_block()). After it has been submitted to 851 * the ipmiconsole engine, it cannot be changed. 852 * 853 * See enum ipmiconsole_ctx_config_option above for config options and 854 * pointer types expected by this function. 855 * 856 * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be 857 * called to determine the cause of the error. 858 */ 859int ipmiconsole_ctx_set_config (ipmiconsole_ctx_t c, 860 ipmiconsole_ctx_config_option_t config_option, 861 void *config_option_value); 862/* 863 * ipmiconsole_ctx_get_config 864 * 865 * Get the value of an advanced configuration value. 866 * 867 * See enum ipmiconsole_ctx_config_option above for config options and 868 * pointer types expected by this function. 869 * 870 * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be 871 * called to determine the cause of the error. 872 */ 873int ipmiconsole_ctx_get_config (ipmiconsole_ctx_t c, 874 ipmiconsole_ctx_config_option_t config_option, 875 void *config_option_value); 876 877/* 878 * ipmiconsole_ctx_errnum 879 * 880 * Returns the errnum of the most recently recorded error for the 881 * context that has not yet been read by the user. 882 */ 883int ipmiconsole_ctx_errnum (ipmiconsole_ctx_t c); 884 885/* 886 * ipmiconsole_ctx_strerror 887 * 888 * Returns a pointer to statically allocated string describing the 889 * error code in errnum. 890 */ 891char *ipmiconsole_ctx_strerror (int errnum); 892 893/* 894 * ipmiconsole_ctx_errormsg 895 * 896 * Returns a pointer to statically allocated string describing the 897 * most recent error for the context. 898 */ 899char *ipmiconsole_ctx_errormsg (ipmiconsole_ctx_t c); 900 901/* 902 * ipmiconsole_ctx_status 903 * 904 * Returns the current context status. Primarily used to determine if 905 * a context submission (submitted non-blocking via 906 * ipmiconsole_engine_submit()) has been established or not. Returns 907 * IPMICONSOLE_CTX_STATUS_ERROR (-1) on error. 908 */ 909ipmiconsole_ctx_status_t ipmiconsole_ctx_status (ipmiconsole_ctx_t c); 910 911/* 912 * ipmiconsole_ctx_fd 913 * 914 * Returns a file descriptor for console reading and writing after it 915 * has been submitted to the engine. Returns -1 on error. 916 * ipmiconsole_ctx_errnum() can be called to determine the cause of 917 * the error. 918 * 919 * If the user closes the file descriptor while the serial over lan 920 * session is established, the session will be torn down in the 921 * engine. 922 * 923 * If an error occurs on the engine side (for example a session 924 * timeout) the other end of the file descriptor pair (from which this 925 * fd is a part of) will be closed. The error can be determined via 926 * ipmiconsole_ctx_errnum(). The user of this file descriptor will 927 * typically see this affect via an EOF on a read() or an EPIPE on a 928 * write(). For alternate file descriptor behavior, see ENGINE flags 929 * above. 930 * 931 * If the user successfully retrieves the file descriptor via this 932 * function, the user is required to close the file descriptor. The 933 * ipmiconsole engine will not do so, with the exception of when the 934 * IPMICONSOLE_ENGINE_CLOSE_FD flag is set. If the user does not 935 * close the file descriptor, a file descriptor leak may occur. 936 */ 937int ipmiconsole_ctx_fd (ipmiconsole_ctx_t c); 938 939/* 940 * ipmiconsole_ctx_generate_break 941 * 942 * Generate a break on an active serial over LAN session. 943 * 944 * Returns 0 on success, -1 on error. ipmiconsole_ctx_errnum() can be 945 * called to determine the cause of the error. 946 */ 947int ipmiconsole_ctx_generate_break (ipmiconsole_ctx_t c); 948 949/* 950 * ipmiconsole_ctx_destroy 951 * 952 * Destroy a context. May not destroy/release the context resources 953 * immediately if the session is still being cleaned up. Will instead 954 * be moved to garbage collection. Will not close file descriptor if 955 * it was retrieved from ipmiconsole_ctx_fd(). User is required to 956 * close it. 957 */ 958void ipmiconsole_ctx_destroy (ipmiconsole_ctx_t c); 959 960/* 961 * ipmiconsole_username_is_valid 962 * 963 * Convenience function to determine if a username is valid. Note that 964 * a NULL pointer, which would result in libipmiconsole using a 965 * default value, is considered an invalid input here. 966 * 967 * Returns 1 if username is valid, 0 if it is not. 968 */ 969int ipmiconsole_username_is_valid (const char *username); 970 971/* 972 * ipmiconsole_password_is_valid 973 * 974 * Convenience function to determine if a password is valid. Note 975 * that a NULL pointer, which would result in libipmiconsole using a 976 * default value, is considered an invalid input here. 977 * 978 * Returns 1 if password is valid, 0 if it is not. 979 */ 980int ipmiconsole_password_is_valid (const char *password); 981 982/* 983 * ipmiconsole_k_g_is_valid 984 * 985 * Convenience function to determine if a k_g is valid. Note that a 986 * NULL pointer, which would result in libipmiconsole using a default 987 * value, is considered an invalid input here. 988 * 989 * Returns 1 if k_g is valid, 0 if it is not. 990 */ 991int ipmiconsole_k_g_is_valid (const unsigned char *k_g, unsigned int k_g_len); 992 993/* 994 * ipmiconsole_privilege_level_is_valid 995 * 996 * Convenience function to determine if a privilege level is valid. 997 * Note that a negative value, which would result in libipmiconsole 998 * using a default value, is considered an invalid input here. 999 * 1000 * Returns 1 if privilege level is valid, 0 if it is not. 1001 */ 1002int ipmiconsole_privilege_level_is_valid (int privilege_level); 1003 1004/* 1005 * ipmiconsole_cipher_suite_id_is_valid 1006 * 1007 * Convenience function to determine if a cipher suite id is valid. 1008 * Note that a negative value, which would result in libipmiconsole 1009 * using a default value, is considered an invalid input here. 1010 * 1011 * Returns 1 if cipher suite id is valid, 0 if it is not. 1012 */ 1013int ipmiconsole_cipher_suite_id_is_valid (int cipher_suite_id); 1014 1015/* 1016 * ipmiconsole_workaround_flags_is_valid 1017 * 1018 * Convenience function to determine if workaround flags are valid. 1019 * Note that a bitmask value of IPMICONSOLE_WORKAROUND_DEFAULT, which 1020 * would result in libipmiconsole using a default value, is considered 1021 * an invalid input here. 1022 * 1023 * Returns 1 if workaround flags are valid, 0 if they are not. 1024 */ 1025int ipmiconsole_workaround_flags_is_valid (unsigned int workaround_flags); 1026 1027#ifdef __cplusplus 1028} 1029#endif 1030 1031#endif /* IPMICONSOLE_H */ 1032