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.

depends:

Python module pyghmi. You can install pyghmi using pip:

pip install pyghmi

configuration:

The following configuration defaults can be define (pillar or config files):

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

Usage can override the config defaults:

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 Data

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 Data

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 Data

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 Data

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 suggests 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]

• 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.

• 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

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