o

�N�g0�@s�dZd
dl
Z
d
dlZd
dlZdg
ZiZiZe
�e	�
Z
dd�Zdd�Zdd	�Z
d
d�Zdd
�Zdd�Zdd�Zdd�Zdd�Zdd�Zdd�Zdd�ZdS)a�
Dell FX2 chassis
================

.. versionadded:: 2015.8.2

Proxy minion interface module for managing Dell FX2 chassis (Dell
Chassis Management Controller version 1.2 and above, iDRAC8 version 2.00
and above)

Dependencies
------------

- :mod:`iDRAC Remote execution module (salt.modules.dracr) <salt.modules.dracr>`
- :mod:`Chassis command shim (salt.modules.chassis) <salt.modules.chassis>`
- :mod:`Dell Chassis States (salt.states.dellchassis) <salt.states.dellchassis>`
- Dell's ``racadm`` command line interface to CMC and iDRAC devices.


**Special Note: SaltStack thanks** `Adobe Corporation <http://adobe.com/>`_
**for their support in creating this proxy minion integration.**

This proxy minion enables Dell FX2 and FX2s (hereafter referred to as
simply "chassis", "CMC", or "FX2") chassis to be treated individually
like a salt-minion.

Since the CMC embedded in the chassis does not run an OS capable of hosting a
Python stack, the chassis can't run a minion directly.  Salt's "Proxy Minion"
functionality enables you to designate another machine to host a minion
process that "proxies" communication from the salt-master.  The master does not
know nor care that the target is not a real minion.

More in-depth conceptual reading on Proxy Minions can be found
:ref:`in the Proxy Minion section <proxy-minion>` of
Salt's documentation.

To configure this integration, follow these steps:

Pillar
------

Proxy minions get their configuration from Salt's Pillar.  Every proxy must
have a stanza in Pillar, and a reference in the Pillar topfile that matches
the ID.  At a minimum for communication with the chassis the pillar should
look like this:

.. code-block:: yaml

    proxy:
      host: <ip or dns name of chassis controller>
      admin_username: <iDRAC username for the CMC, usually 'root'>
      fallback_admin_username: <username to try if the first fails>
      passwords:
        - first_password
        - second_password
        - third-password
      proxytype: fx2

The ``proxytype`` line above is critical, it tells Salt which interface to load
from the ``proxy`` directory in Salt's install hierarchy, or from ``/srv/salt/_proxy``
on the salt-master (if you have created your own proxy module, for example).

The proxy integration will try the passwords listed in order.  It is
configured this way so you can have a regular password, a potential
fallback password, and the third password can be the one you intend
to change the chassis to use.  This way, after it is changed, you
should not need to restart the proxy minion--it should just pick up the
third password in the list.  You can then change pillar at will to
move that password to the front and retire the unused ones.

Beware, many Dell CMC and iDRAC units are configured to lockout
IP addresses or users after too many failed password attempts.  This can
generate user panic in the form of "I no longer know what the password is!!!".
To mitigate panic try the web interface from a different IP, or setup a
emergency administrator user in the CMC before doing a wholesale
password rotation.

The automatic lockout can be disabled via Salt with the following:

.. code-block:: bash

    salt <cmc> chassis.cmd set_general cfgRacTuning cfgRacTuneIpBlkEnable 0

and then verified with

.. code-block:: bash

    salt <cmc> chassis.cmd get_general cfgRacTuning cfgRacTuneIpBlkEnable



salt-proxy
----------

After your pillar is in place, you can test the proxy.  The proxy can run on
any machine that has network connectivity to your salt-master and to the chassis in question.
SaltStack recommends that this machine also run a regular minion, though
it is not strictly necessary.

On the machine that will run the proxy, make sure there is an ``/etc/salt/proxy``
file with at least the following in it:

.. code-block:: yaml

    master: <ip or hostname of salt-master>

You can start the proxy with

.. code-block:: bash

    salt-proxy --proxyid <id you want to give the chassis>

You may want to add ``-l debug`` to run the above in the foreground in debug
mode just to make sure everything is OK.

Next, accept the key for the proxy on your salt-master, just like you would
for a regular minion:

.. code-block:: bash

    salt-key -a <id you want to give the chassis>

You can confirm that the pillar data is in place for the proxy:

.. code-block:: bash

    salt <id> pillar.items

And now you should be able to ping the chassis to make sure it is responding:

.. code-block:: bash

    salt <id> test.ping

At this point you can execute one-off commands against the chassis.  For
example, you can get the chassis inventory:

.. code-block:: bash

    salt <id> chassis.cmd inventory

Note that you don't need to provide credentials or an ip/hostname.  Salt knows
to use the credentials you stored in Pillar.

It's important to understand how this particular proxy works.
:mod:`Salt.modules.dracr <salt.modules.dracr>` is a standard Salt execution
module.  If you pull up the docs for it you'll see that almost every function
in the module takes credentials and a target host.  When credentials and a host
aren't passed, Salt runs ``racadm`` against the local machine.  If you wanted
you could run functions from this module on any host where an appropriate
version of ``racadm`` is installed, and that host would reach out over the network
and communicate with the chassis.

``Chassis.cmd`` acts as a "shim" between the execution module and the proxy.  Its
first parameter is always the function from salt.modules.dracr to execute.  If the
function takes more positional or keyword arguments you can append them to the call.
It's this shim that speaks to the chassis through the proxy, arranging for the
credentials and hostname to be pulled from the pillar section for this proxy minion.

Because of the presence of the shim, to lookup documentation for what
functions you can use to interface with the chassis, you'll want to
look in :mod:`salt.modules.dracr <salt.modules.dracr>` instead
of :mod:`salt.modules.chassis <salt.modules.chassis>`.

States
------

Associated states are thoroughly documented in :mod:`salt.states.dellchassis <salt.states.dellchassis>`.
Look there to find an example structure for pillar as well as an example
``.sls`` file for standing up a Dell Chassis from scratch.

�NZfx2cCstj
j�d
�
s	dSdS)z6
    Only return if all the modules are available
    Zracadm)Fz0fx2 proxy minion needs "racadm" to be installed.T)�salt�utils�path�which�rr�B/opt/saltstack/salt/lib/python3.10/site-packages/salt/proxy/fx2.py�__virtual__�s

rc
Cs8d
|dv
r
t�
d�

dS|dd
td
<t�\}
}dS)a�

    This function gets called when the proxy starts up.
    We check opts to see if a fallback user and password are supplied.
    If they are present, and the primary credentials don't work, then
    we try the backup before failing.

    Whichever set of credentials works is placed in the persistent
    DETAILS dictionary and will be used for further communication with the
    chassis.
    �host�proxyz,No "host" key found in pillar for this proxyFN)�log�critical�DETAILS�find_credentials)�opts�username�passwordrrr�init�s



rcCst�
d
d�S)zc
    Return the admin_username in the DETAILS dictionary, or root if there
    is none present
    �admin_username�root)r
�getrrrrr�srcCs"d
tv
rt
�d�

dSt�d
d�S)zz
    Return the admin_password in the DETAILS dictionary, or 'calvin'
    (the Dell default) if there is none present
    �admin_passwordz?proxy.fx2: No admin_password in DETAILS, returning Dell default�calvin)r
r�inforrrrrr�s


rcCstd
S)Nr	)
r
rrrrr	�s
r	cCs2td
||
|d�}|�
dd�dkr|}|Si}|S)�0
    Get the grains from the proxied device
    �dracr.system_info�r	rr�retcoder
)�__salt__r)r	�userr�
r�GRAINS_CACHErrr�_grains�s
�
�
r!cCs tst
td
tdtd�StS)rr	rr)r r!r
rrrr�grains
s


�r"c

Cs
i}t�S)
z4
    Refresh the grains from the proxied device
    )
r")
r rrr�grains_refresh
s
r#c
Cs
td
�
dd�g
}dt�
d
�
vr|�td
�
d�
�

|D]d}
td
dD][}tdtd
d|
|d�}z'|�
d	d
�d
urY|
td<|td<|
td
d<|td
d<|
|fW

SWq$ty


|
td<|td<|
td
d<|td
d<|
|fY

Swqt�d�

d
S)z\
    Cycle through all the possible credentials and return the first one that
    works
    r
rrZfallback_admin_usernameZ	passwordszdracr.get_chassis_namer	rrNrzIproxy fx2.find_credentials found no valid credentials, using Dell default)rr)	Z
__pillar__r�appendrr
�__opts__�AttributeErrorr�debug)Z	usernamesr�pwdrrrrr
s<







�





�



��
�rc
Os�t|�
D]}|�
d
�
r|�|�

qd|tv
r!dd|dd�}ntd||
i|�
�
}|dkrTd|vrB|dtdd	<|dtd	<d
|vrT|d
tdd<|d
td<|S)a�

    This function is called by the :mod:`salt.modules.chassis.cmd <salt.modules.chassis.cmd>`
    shim.  It then calls whatever is passed in ``cmd``
    inside the :mod:`salt.modules.dracr <salt.modules.dracr>`
    module.

    :param cmd: The command to call inside salt.modules.dracr
    :param args: Arguments that need to be passed to that command
    :param kwargs: Keyword arguments that need to be passed to that command
    :return: Passthrough the return from the dracr module.

    Z__pub_zdracr.���z is not available)r�messageZchange_passwordrr
rrr)�list�
startswith�poprr%r
)�cmd�args�kwargs�
k�retrrr�chconfig>
s



�






r3c
Cs6td
t
dt
dt
dd�}|�dd�dkrd	Sd
S)zp
    Is the chassis responding?

    :return: Returns False if the chassis didn't respond, True otherwise.

    rr	rrrrr
�
FT)rr
r�	Exception)
rrrr�pinga
s


�
r6c

Cst�
d
�

dS)z`
    Shutdown the connection to the proxied device.
    For this proxy shutdown is a no-op.
    zfx2 proxy shutdown() called...N)rr')
rrrr�shutdownw
sr7)�__doc__�loggingZsalt.utils.httprZsalt.utils.pathZ__proxyenabled__r r
�	getLogger�__file__rrrrrr	r!r"r#rr3r6r7rrrr�<module>
s*.


	'#