o

�N�g�K�@s�dZd
dl
Z
d
dlZd
dlmZ
d
dlmZmZ
d
dlm	Z	
dg
Z
zd
dlZdZWne
y4


dZYn
wiZiZe
�e�
ZdZd	d
�Zdd�Zd
d�Zdd�Zdd�Zdd�Zdd�Zdd�Zddd�
Zdd�Zdd�ZdS) a�&
Proxy Minion interface module for managing VMware ESXi hosts.

.. Warning::
    This module will be deprecated in a future release of Salt. VMware strongly
    recommends using the
    `VMware Salt extensions <https://docs.saltproject.io/salt/extensions/salt-ext-modules-vmware/en/latest/all.html>`_
    instead of the ESXi module. Because the Salt extensions are newer and
    actively supported by VMware, they are more compatible with current versions
    of ESXi and they work well with the latest features in the VMware product
    line.


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

This proxy minion enables VMware ESXi (hereafter referred to as simply 'ESXi')
hosts to be treated individually like a Salt Minion.

Since the ESXi host may not necessarily run on an OS capable of hosting a
Python stack, the ESXi host can't run a Salt 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" Salt Minion.

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


Dependencies
============

- pyVmomi Python Module
- ESXCLI


pyVmomi
-------

PyVmomi can be installed via pip:

.. code-block:: bash

    pip install pyVmomi

.. note::

    Version 6.0 of pyVmomi has some problems with SSL error handling on certain
    versions of Python. If using version 6.0 of pyVmomi, Python 2.6,
    Python 2.7.9, or newer must be present. This is due to an upstream dependency
    in pyVmomi 6.0 that is not supported in Python versions 2.7 to 2.7.8. If the
    version of Python is not in the supported range, you will need to install an
    earlier version of pyVmomi. See `Issue #29537`_ for more information.

.. _Issue #29537: https://github.com/saltstack/salt/issues/29537

Based on the note above, to install an earlier version of pyVmomi than the
version currently listed in PyPi, run the following:

.. code-block:: bash

    pip install pyVmomi==5.5.0.2014.1.1

The 5.5.0.2014.1.1 is a known stable version that this original ESXi State
Module was developed against.

ESXCLI
------

Currently, about a third of the functions used in the vSphere Execution Module require
the ESXCLI package be installed on the machine running the Proxy Minion process.

The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware
provides vCLI package installation instructions for `vSphere 5.5`_ and
`vSphere 6.0`_.

.. _vSphere 5.5: http://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html
.. _vSphere 6.0: http://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html

Once all of the required dependencies are in place and the vCLI package is
installed, you can check to see if you can connect to your ESXi host or vCenter
server by running the following command:

.. code-block:: bash

    esxcli -s <host-location> -u <username> -p <password> system syslog config get

If the connection was successful, ESXCLI was successfully installed on your system.
You should see output related to the ESXi host's syslog configuration.


Configuration
=============
To use this integration proxy module, please configure the following:

Pillar
------

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

.. code-block:: yaml

    proxy:
      proxytype: esxi
      host: <ip or dns name of esxi host>
      username: <ESXi username>
      passwords:
        - first_password
        - second_password
        - third_password
      credstore: <path to credential store>

proxytype
^^^^^^^^^
The ``proxytype`` key and value pair is critical, as 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). To use this ESXi Proxy Module, set this to
``esxi``.

host
^^^^
The location, or ip/dns, of the ESXi host. Required.

username
^^^^^^^^
The username used to login to the ESXi host, such as ``root``. Required.

passwords
^^^^^^^^^
A list of passwords to be used to try and login to the ESXi host. At least
one password in this list is required.

The proxy integration will try the passwords listed in order. It is
configured this way so you can have a regular password and the password you
may be updating for an ESXi host either via the
:mod:`vsphere.update_host_password <salt.modules.vsphere.update_host_password>`
execution module function or via the
:mod:`esxi.password_present <salt.states.esxi.password_present>` state
function. This way, after the password is changed, you should not need to
restart the proxy minion--it should just pick up the new password
provided in the list. You can then change pillar at will to move that
password to the front and retire the unused ones.

This also allows you to use any number of potential fallback passwords.

.. note::

    When a password is changed on the host to one in the list of possible
    passwords, the further down on the list the password is, the longer
    individual commands will take to return. This is due to the nature of
    pyVmomi's login system. We have to wait for the first attempt to fail
    before trying the next password on the list.

    This scenario is especially true, and even slower, when the proxy
    minion first starts. If the correct password is not the first password
    on the list, it may take up to a minute for ``test.ping`` to respond
    with a ``True`` result. Once the initial authorization is complete, the
    responses for commands will be a little faster.

    To avoid these longer waiting periods, SaltStack recommends moving the
    correct password to the top of the list and restarting the proxy minion
    at your earliest convenience.

protocol
^^^^^^^^
If the ESXi host is not using the default protocol, set this value to an
alternate protocol. Default is ``https``.

port
^^^^
If the ESXi host is not using the default port, set this value to an
alternate port. Default is ``443``.

credstore
^^^^^^^^^
If the ESXi host is using an untrusted SSL certificate, set this value to
the file path where the credential store is located. This file is passed to
``esxcli``. Default is ``<HOME>/.vmware/credstore/vicredentials.xml`` on Linux
and ``<APPDATA>/VMware/credstore/vicredentials.xml`` on Windows.

.. note::

    ``HOME`` variable is sometimes not set for processes running as system
    services. If you want to rely on the default credential store location,
    make sure ``HOME`` is set for the proxy process.

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
ESXi host in question. SaltStack recommends that the machine running the
salt-proxy process 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 then start the salt-proxy process with:

.. code-block:: bash

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

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 gave the esxi host>

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 ESXi host to make sure it is
responding:

.. code-block:: bash

    salt <id> test.ping

At this point you can execute one-off commands against the host. For
example, you can get the ESXi host's system information:

.. code-block:: bash

    salt <id> esxi.cmd system_info

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.vsphere <salt.modules.vsphere>` 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 commands
through ``pyVmomi`` against the local machine. If you wanted, you could run
functions from this module on any host where an appropriate version of
``pyVmomi`` is installed, and that host would reach out over the network
and communicate with the ESXi host.

``esxi.cmd`` acts as a "shim" between the execution module and the proxy. Its
first parameter is always the function from salt.modules.vsphere. If the
function takes more positional or keyword arguments you can append them to the
call. It's this shim that speaks to the ESXi host 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 ESXi host, you'll want to
look in :mod:`salt.modules.vsphere <salt.modules.vsphere>`
instead of :mod:`salt.modules.esxi <salt.modules.esxi>`.


States
------

Associated states are thoroughly documented in
:mod:`salt.states.esxi <salt.states.esxi>`. Look there
to find an example structure for Pillar as well as an example ``.sls`` file
for standing up an ESXi host from scratch.

�N)
�EsxiProxySchema)�InvalidConfigError�SaltSystemExit)
�mergeZesxiTFc
Cstrt
Sd
S)z>
    Only load if the ESXi execution module is available.
    )Fz*The ESXi Proxy Minion module did not load.)�HAS_JSONSCHEMA�__virtualname__�rr�C/opt/saltstack/salt/lib/python3.10/site-packages/salt/proxy/esxi.py�__virtual__4
s
r
c

Cs t�
d
t���
t�
d�

t��}
t�d|
�
t|�di�t	�di��}t�d|�
zt
�||
�
Wnt
jj
yD
}
zt|�
�
d}~w
w|dtd<d|v
rZd	|v
rZt�d
�

dSd|vr�d|v
rit�d
�

dSd|v
rtt�d�

dS|d}zt|�
\}}Wnty�
}
z
t�d|�
WYd}~dSd}~w
w|td<|td<|td<|�d�
td<|�d�
td<dSd	|v�
rw|d	}|�d�
s�t�d�

|dtd<d|v
r�t�d�

dS|d}	dD]}
||
t|
<q�|	dk�
rd|v
r�t�d
�

dSd|v
�
rt|d�
dk�
rt�d�

dSdD]	}
||
t|
<�
qn)|	dk�
rDd|v
�
r,t�d �

dSd!|v
�
r8t�d"�

dSd#D]	}
||
t|
<�
q:|	dk�
rwt�
d$�

zttd	�
\}}|td<Wnt�
yv
}
z
t�d|�
WYd}~dSd}~w
w|�dd%�td<|�dd&�td<|�d'�
td'<dS)(z�
    This function gets called when the proxy starts up. For
    ESXi devices, the host, login credentials, and, if configured,
    the protocol and port are cached.
    z(Initting esxi proxy module in process %szValidating esxi proxy inputzesxi_proxy_schema = %s�proxyzproxy_conf = %sNZ	proxytype�host�vcenterzANeither 'host' nor 'vcenter' keys found in pillar for this proxy.F�usernamez1No 'username' key found in pillar for this proxy.�	passwordsz2No 'passwords' key found in pillar for this proxy.z	Error: %s�password�protocol�portT�	esxi_hostz2No 'esxi_host' key found in pillar for this proxy.�	mechanismz2No 'mechanism' key found in pillar for this proxy.)r
r�userpassr
zWMechanism is set to 'userpass' , but no 'passwords' key found in pillar for this proxy.)rrZsspi�domainzPMechanism is set to 'sspi' , but no 'domain' key found in pillar for this proxy.�	principalzSMechanism is set to 'sspi' , but no 'principal' key found in pillar for this proxy.)rrzORetrieving credentials and testing vCenter connection for mehchanism 'userpass'�httpsZ443�	credstore)�log�debug�os�getpidrZ	serializeZtracer�get�
__pillar__�
jsonschema�validate�
exceptionsZValidationErrorr�DETAILS�critical�find_credentialsr�len)�optsZschemaZ
proxy_conf�excrrr�errr
r�keyrrr	�init>
s�









��


�












��























�

�




�



�



�




��

r+cCs tst
td
tdtd�StS)z/
    Get the grains from the proxy device.
    rrr)�GRAINS_CACHE�_grainsr#rrrr	�grains�
s

r.c

Cs
i}t�S)
z3
    Refresh the grains from the proxy device.
    )
r.)
r,rrr	�grains_refresh�
s
r/c

Cs�t�
d
�
rdStddkr>ttd�

ztdtdtdtdd	�
WdSty=
}
zt�|�

WYd
}~dSd
}~w
wdS)a

    Returns True if connection is to be done via a vCenter (no connection is attempted).
    Check to see if the host is responding when connecting directly via an ESXi
    host.

    CLI Example:

    .. code-block:: bash

        salt esxi-host test.ping
    rTrrr�vsphere.system_inforr�rrrNF)r#rr%�__salt__rr�warning)
r)rrr	�ping�
s"







��


��r4cCst�
d
�

dS)z_
    Shutdown the connection to the proxy device. For this proxy,
    shutdown is a no-op.
    zESXi proxy shutdown() called...N)rrrrrr	�shutdown�
sr5c
Os�|D]}|�d
�
r|�
|�

qtd|d<td|d<td|d<td|d<td|d<td|d<d|tv
rBd	d|d
d�Std||
i|�
�
S)a�

    This function is called by the
    :mod:`salt.modules.esxi.cmd <salt.modules.esxi.cmd>` shim.
    It then calls whatever is passed in ``cmd`` inside the
    :mod:`salt.modules.vsphere <salt.modules.vsphere>` module.
    Passes the return through from the vsphere module.

    cmd
        The command to call inside salt.modules.vsphere

    args
        Arguments that need to be passed to that command.

    kwargs
        Keyword arguments that need to be passed to that command.

    Z__pub_rrrrrrzvsphere.���z is not available.)�retcode�message)�
startswith�popr#r2)�cmd�args�kwargs�
krrr	�	ch_config�
s



�





r?c

Cs�td
�
dd�g
}
td
d}|
D].}|D])}ztd|||d�}Wn	ty+


Yqw|r>|td<|td<||f

Sqqtd�
�
)	z]
    Cycle through all the possible credentials and return the first one that
    works.
    rr�rootrr0r1rz@Cannot complete login due to an incorrect user name or password.)rrr2rr#)rZ
user_namesr�userr�retrrr	r%	s(





��


��
�r%cCs4tt
d
�
\}}td||||
|d�}t�|�

tS)z@
    Helper function to the grains from the proxied device.
    rr0)rrrrr)r%r#r2r,�update)rrrrrrBrrr	r-%s


�

r-cCsd
tvrdSdS)Nr
TF�
r#rrrr	�is_connected_via_vcenter1s
rEc
CstS)
z"
    Return the proxy details
    rDrrrr	�get_details5srF)NN)�__doc__�loggingrZsalt.config.schemas.esxirZsalt.exceptionsrrZsalt.utils.dictupdaterZ__proxyenabled__r r�ImportErrorr,r#�	getLogger�__file__rrr
r+r.r/r4r5r?r%r-rErFrrrr	�<module>
s<





�


p	$