salt.modules.ipmi¶

Support IPMI commands over LAN. This module does not talk to the local systems hardware through IPMI drivers. It uses a python module pyghmi.

pip install pyghmi

ipmi.config:
    api_host: 127.0.0.1
    api_user: admin
    api_pass: apassword
    api_port: 623
    api_kg: None

salt-call ipmi.get_user api_host=myipmienabled.system
                        api_user=admin api_pass=pass
                        uid=1

salt.modules.ipmi.create_user(uid, name, password, channel=14, callback=False, link_auth=True, ipmi_msg=True, privilege_level='administrator', **kwargs)¶

create/ensure a user is created with provided settings.

Parameters:	privilege_level -- User Privilege Limit. (Determines the maximum privilege level that the user is allowed to switch to on the specified channel.) * callback * user * operator * administrator * proprietary * no_access kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.create_user uid=2 name=steverweber api_host=172.168.0.7 api_pass=nevertell

salt.modules.ipmi.fast_connect_test(**kwargs)¶

Returns True if connection success. This uses an aggressive timeout value!

Parameters:	kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.fast_connect_test api_host=172.168.0.9

salt.modules.ipmi.get_bootdev(**kwargs)¶

Get current boot device override information.

Provides the current requested boot device. Be aware that not all IPMI devices support this. Even in BMCs that claim to, occasionally the BIOS or UEFI fail to honor it. This is usually only applicable to the next reboot.

Parameters:	kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Example:

salt-call ipmi.get_bootdev api_host=127.0.0.1 api_user=admin api_pass=pass

salt.modules.ipmi.get_channel_access(channel=14, read_mode='non_volatile', **kwargs)¶

:param kwargs:api_host='127.0.0.1' api_user='admin' api_pass='example' api_port=623

Parameters:	channel -- number [1:7] read_mode -- non_volatile = get non-volatile Channel Access volatile = get present volatile (active) setting of Channel Access kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

return

A Python dict with the following keys/values:

{
    alerting:
    per_msg_auth:
    user_level_auth:
    access_mode:{ (ONE OF)
        0: 'disabled',
        1: 'pre_boot',
        2: 'always',
        3: 'shared'
    }
    privilege_level: { (ONE OF)
        1: 'callback',
        2: 'user',
        3: 'operator',
        4: 'administrator',
        5: 'proprietary',
    }
}

CLI Examples:

salt-call ipmi.get_channel_access channel=1

salt.modules.ipmi.get_channel_info(channel=14, **kwargs)¶

Get channel info

Parameters:	channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

return

channel session supports:

- no_session: channel is session-less
- single: channel is single-session
- multi: channel is multi-session
- auto: channel is session-based (channel could alternate between
    single- and multi-session operation, as can occur with a
    serial/modem channel that supports connection mode auto-detect)

CLI Examples:

salt-call ipmi.get_channel_info

salt.modules.ipmi.get_channel_max_user_count(channel=14, **kwargs)¶

Get max users in channel

Parameters:	channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None
Returns:	int -- often 16

CLI Examples:

salt-call ipmi.get_channel_max_user_count

salt.modules.ipmi.get_health(**kwargs)¶

Get Summarize health

This provides a summary of the health of the managed system. It additionally provides an iterable list of reasons for warning, critical, or failed assessments.

good health: {'badreadings': [], 'health': 0}

Parameters:	kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Example:

salt-call ipmi.get_health api_host=127.0.0.1 api_user=admin api_pass=pass

salt.modules.ipmi.get_power(**kwargs)¶

Get current power state

The response, if successful, should contain 'powerstate' key and either 'on' or 'off' to indicate current state.

Parameters:	kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Example:

salt-call ipmi.get_power api_host=127.0.0.1 api_user=admin api_pass=pass

salt.modules.ipmi.get_sensor_data(**kwargs)¶

Get sensor readings

Iterates sensor reading objects

Parameters:	kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Example:

salt-call ipmi.get_sensor_data api_host=127.0.0.1 api_user=admin api_pass=pass

salt.modules.ipmi.get_user(uid, channel=14, **kwargs)¶

Get user from uid and access on channel

Parameters:	uid -- user number [1:16] channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

return

name: (str)
uid: (int)
channel: (int)
access:
    - callback (bool)
    - link_auth (bool)
    - ipmi_msg (bool)
    - privilege_level: (str)[callback, user, operatorm administrator,
                            proprietary, no_access]

CLI Examples:

salt-call ipmi.get_user uid=2

salt.modules.ipmi.get_user_access(uid, channel=14, **kwargs)¶

Get user access

Parameters:	uid -- user number [1:16] channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

return

channel_info:
    - max_user_count = maximum number of user IDs on this channel
    - enabled_users = count of User ID slots presently in use
    - users_with_fixed_names = count of user IDs with fixed names
access:
    - callback
    - link_auth
    - ipmi_msg
    - privilege_level: [reserved, callback, user, operator
                       administrator, proprietary, no_access]

CLI Examples:

salt-call ipmi.get_user_access uid=2

salt.modules.ipmi.get_user_name(uid, return_none_on_error=True, **kwargs)¶

Get user name

Parameters:	uid -- user number [1:16] return_none_on_error -- return None on error kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.get_user_name uid=2

salt.modules.ipmi.get_users(channel=14, **kwargs)¶

get list of users and access information

Parameters:	channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None
Returns:	name: (str) uid: (int) channel: (int) access: callback (bool) link_auth (bool) ipmi_msg (bool) privilege_level: (str)[callback, user, operatorm administrator, proprietary, no_access]

CLI Examples:

salt-call ipmi.get_users api_host=172.168.0.7

salt.modules.ipmi.raw_command(netfn, command, bridge_request=None, data=(), retry=True, delay_xmit=None, **kwargs)¶

Send raw ipmi command

This allows arbitrary IPMI bytes to be issued. This is commonly used for certain vendor specific commands.

Parameters:	netfn -- Net function number command -- Command value bridge_request -- The target slave address and channel number for the bridge request. data -- Command data as a tuple or list kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None
Returns:	dict -- The response from IPMI device

CLI Examples:

salt-call ipmi.raw_command netfn=0x06 command=0x46 data=[0x02]
# this will return the name of the user with id 2 in bytes

salt.modules.ipmi.set_bootdev(bootdev='default', persist=False, uefiboot=False, **kwargs)¶

Set boot device to use on next reboot

Parameters:

bootdev -- network: Request network boot hd: Boot from hard drive safe: Boot from hard drive, requesting 'safe mode' optical: boot from CD/DVD/BD drive setup: Boot into setup utility default: remove any IPMI directed boot device request persist -- If true, ask that system firmware use this device beyond next boot. Be aware many systems do not honor this uefiboot -- If true, request UEFI boot explicitly. Strictly speaking, the spec sugests that if not set, the system should BIOS boot and offers no "don't care" option. In practice, this flag not being set does not preclude UEFI boot on any system I've encountered. kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

Returns:

dict or True -- If callback is not provided, the response

CLI Examples:

salt-call ipmi.set_bootdev bootdev=network persist=True

salt.modules.ipmi.set_channel_access(channel=14, access_update_mode='non_volatile', alerting=False, per_msg_auth=False, user_level_auth=False, access_mode='always', privilege_update_mode='non_volatile', privilege_level='administrator', **kwargs)¶

Set channel access

Parameters:

channel -- number [1:7] access_update_mode -- 'dont_change' = don't set or change Channel Access 'non_volatile' = set non-volatile Channel Access 'volatile' = set volatile (active) setting of Channel Access alerting -- PEF Alerting Enable/Disable True = enable PEF Alerting False = disable PEF Alerting on this channel (Alert Immediate command can still be used to generate alerts) per_msg_auth -- Per-message Authentication True = enable False = disable Per-message Authentication. [Authentication required to activate any session on this channel, but authentication not used on subsequent packets for the session.] user_level_auth -- User Level Authentication Enable/Disable. True = enable User Level Authentication. All User Level commands are to be authenticated per the Authentication Type that was negotiated when the session was activated. False = disable User Level Authentication. Allow User Level commands to be executed without being authenticated. If the option to disable User Level Command authentication is accepted, the BMC will accept packets with Authentication Type set to None if they contain user level commands. For outgoing packets, the BMC returns responses with the same Authentication Type that was used for the request. access_mode -- Access Mode for IPMI messaging (PEF Alerting is enabled/disabled separately from IPMI messaging) disabled = disabled for IPMI messaging pre_boot = pre-boot only channel only available when system is in a powered down state or in BIOS prior to start of boot. always = channel always available regardless of system mode. BIOS typically dedicates the serial connection to the BMC. shared = same as always available, but BIOS typically leaves the serial port available for software use. privilege_update_mode -- Channel Privilege Level Limit. This value sets the maximum privilege level that can be accepted on the specified channel. dont_change = don't set or change channel Privilege Level Limit non_volatile = non-volatile Privilege Level Limit according volatile = volatile setting of Privilege Level Limit privilege_level -- Channel Privilege Level Limit reserved = unused callback user operator administrator proprietary = used by OEM kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.set_channel_access privilege_level='administrator'

salt.modules.ipmi.set_identify(on=True, duration=600, **kwargs)¶

Request identify light

Request the identify light to turn off, on for a duration, or on indefinitely. Other than error exceptions,

Parameters:	on -- Set to True to force on or False to force off duration -- Set if wanting to request turn on for a duration in seconds, None = indefinitely. kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.set_identify

salt.modules.ipmi.set_power(state='power_on', wait=True, **kwargs)¶

Request power state change

Parameters:

name -- power_on -- system turn on power_off -- system turn off (without waiting for OS) shutdown -- request OS proper shutdown reset -- reset (without waiting for OS) boot -- If system is off, then 'on', else 'reset' ensure -- If (bool True), do not return until system actually completes requested state change for 300 seconds. If a non-zero (int), adjust the wait time to the requested number of seconds kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

Returns:

dict -- A dict describing the response retrieved

CLI Examples:

salt-call ipmi.set_power state=shutdown wait=True

salt.modules.ipmi.set_user_access(uid, channel=14, callback=True, link_auth=True, ipmi_msg=True, privilege_level='administrator', **kwargs)¶

Set user access

Parameters:

uid -- user number [1:16] channel -- number [1:7] link_auth -- User Link authentication enable/disable (used to enable whether this user's name and password information will be used for link authentication, e.g. PPP CHAP) for the given channel. Link authentication itself is a global setting for the channel and is enabled/disabled via the serial/modem configuration parameters. ipmi_msg -- User IPMI Messaging: (used to enable/disable whether this user's name and password information will be used for IPMI Messaging. In this case, 'IPMI Messaging' refers to the ability to execute generic IPMI commands that are not associated with a particular payload type. For example, if IPMI Messaging is disabled for a user, but that user is enabled for activating the SOL payload type, then IPMI commands associated with SOL and session management, such as Get SOL Configuration Parameters and Close Session are available, but generic IPMI commands such as Get SEL Time are unavailable.) privilege_level -- User Privilege Limit. (Determines the maximum privilege level that the user is allowed to switch to on the specified channel.) callback user operator administrator proprietary no_access kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

Parm callback:

User Restricted to Callback False = User Privilege Limit is determined by the User Privilege Limit parameter, below, for both callback and non-callback connections. True = User Privilege Limit is determined by the User Privilege Limit parameter for callback connections, but is restricted to Callback level for non-callback connections. Thus, a user can only initiate a Callback when they 'call in' to the BMC, but once the callback connection has been made, the user could potentially establish a session as an Operator.

CLI Examples:

salt-call ipmi.set_user_access uid=2 privilege_level='operator'

salt.modules.ipmi.set_user_name(uid, name, **kwargs)¶

Set user name

Parameters:	uid -- user number [1:16] name -- username (limit of 16bytes) kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.set_user_name uid=2 name='steverweber'

salt.modules.ipmi.set_user_password(uid, mode='set_password', password=None, **kwargs)¶

Set user password and (modes)

Parameters:	uid -- id number of user. see: get_names_uid()['name'] mode -- disable = disable user connections enable = enable user connections set_password = set or ensure password test_password = test password is correct password -- max 16 char string (optional when mode is [disable or enable]) kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None
Returns:	True on success when mode = test_password, return False on bad password

CLI Example:

salt-call ipmi.set_user_password api_host=127.0.0.1 api_user=admin api_pass=pass
                                 uid=1 password=newPass
salt-call ipmi.set_user_password uid=1 mode=enable

salt.modules.ipmi.user_delete(uid, channel=14, **kwargs)¶

Delete user (helper)

Parameters:	uid -- user number [1:16] channel -- number [1:7] kwargs -- api_host=127.0.0.1 api_user=admin api_pass=example api_port=623 api_kg=None

CLI Examples:

salt-call ipmi.user_delete uid=2