o

�N�g#�@s�dZd
dl
Z
d
dlZd
dlZd
dlZd
dlZd
dlZddddddd	d
�ZdZe�	e�
Z
dd
�ZGdd�de�Z
dd�Zdd�Zdd�Zd%dd�
Zdd�Zdd�Zdd�Zdd�Zd d!�Zd"d#�Zed$krie�
dSdS)&a�
A minimalist REST API for Salt
==============================

This ``rest_wsgi`` module provides a no-frills REST interface for sending
commands to the Salt master. There are no dependencies.

Extra care must be taken when deploying this module into production. Please
read this documentation in entirety.

All authentication is done through Salt's :ref:`external auth <acl-eauth>`
system.

Usage
=====

* All requests must be sent to the root URL (``/``).
* All requests must be sent as a POST request with JSON content in the request
  body.
* All responses are in JSON.

.. seealso:: :py:mod:`rest_cherrypy <salt.netapi.rest_cherrypy.app>`

    The :py:mod:`rest_cherrypy <salt.netapi.rest_cherrypy.app>` module is
    more full-featured, production-ready, and has builtin security features.

Deployment
==========

The ``rest_wsgi`` netapi module is a standard Python WSGI app. It can be
deployed one of two ways.

Using a WSGI-compliant web server
---------------------------------

This module may be run via any WSGI-compliant production server such as Apache
with mod_wsgi or Nginx with FastCGI.

It is strongly recommended that this app be used with a server that supports
HTTPS encryption since raw Salt authentication credentials must be sent with
every request. Any apps that access Salt through this interface will need to
manually manage authentication credentials (either username and password or a
Salt token). Tread carefully.

:program:`salt-api` using a development-only server
---------------------------------------------------

If run directly via the salt-api daemon it uses the `wsgiref.simple_server()`__
that ships in the Python standard library. This is a single-threaded server
that is intended for testing and development. **This server does not use
encryption**; please note that raw Salt authentication credentials must be sent
with every HTTP request.

**Running this module via salt-api is not recommended!**

In order to start this module via the ``salt-api`` daemon the following must be
put into the Salt master config::

    rest_wsgi:
        port: 8001

.. __: http://docs.python.org/2/library/wsgiref.html#module-wsgiref.simple_server

Usage examples
==============

.. http:post:: /

    **Example request** for a basic ``test.ping``::

        % curl -sS -i \
                -H 'Content-Type: application/json' \
                -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local","tgt":"*","fun":"test.ping"}]' localhost:8001

    **Example response**:

    .. code-block:: http

        HTTP/1.0 200 OK
        Content-Length: 89
        Content-Type: application/json

        {"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}

    **Example request** for an asynchronous ``test.ping``::

        % curl -sS -i \
                -H 'Content-Type: application/json' \
                -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"local_async","tgt":"*","fun":"test.ping"}]' localhost:8001

    **Example response**:

    .. code-block:: http

        HTTP/1.0 200 OK
        Content-Length: 103
        Content-Type: application/json

        {"return": [{"jid": "20130412192112593739", "minions": ["ms--4", "ms--3", "ms--2", "ms--1", "ms--0"]}]}

    **Example request** for looking up a job ID::

        % curl -sS -i \
                -H 'Content-Type: application/json' \
                -d '[{"eauth":"pam","username":"saltdev","password":"saltdev","client":"runner","fun":"jobs.lookup_jid","jid":"20130412192112593739"}]' localhost:8001

    **Example response**:

    .. code-block:: http

        HTTP/1.0 200 OK
        Content-Length: 89
        Content-Type: application/json

        {"return": [{"ms--4": true, "ms--3": true, "ms--2": true, "ms--1": true, "ms--0": true}]}

:form lowstate: A list of lowstate data appropriate for the
    :ref:`client <client-apis>` interface you are calling.
:status 200: success
:status 401: authentication required

�Nz200 OKz400 BAD REQUESTz401 UNAUTHORIZEDz
404 NOT FOUNDz405 METHOD NOT ALLOWEDz406 NOT ACCEPTABLEz500 INTERNAL SERVER ERROR)���
�
i�
�
�
��
Z	rest_wsgic
Cst�
ti�}d
|vrtSdS)N�portF)�__opts__�get�__virtualname__)
�mod_opts�r
�I/opt/saltstack/salt/lib/python3.10/site-packages/salt/netapi/rest_wsgi.py�__virtual__�s

rc@seZ
dZd
Zdd�ZdS)�	HTTPErrorzM
    A custom exception that can take action based on an HTTP error code
    cCs |
|_t
�||
�d
|���
dS)Nz: )�code�	Exception�__init__)�selfr�messager
r
rr�s

zHTTPError.__init__N)�__name__�
__module__�__qualname__�__doc__rr
r
r
rr�s
rc

CsTzt�
|�

Wd
Sty)
}

z|
jtjkrtj�|�
rn
�WYd
}
~
d
Sd
}
~
w
w)z?
    mkdir -p
    http://stackoverflow.com/a/600612/127816
    N)�os�makedirs�OSError�errnoZEEXIST�path�isdir)r�excr
r
r�mkdir_p�s



���r!c
Cs.|�d
d�}
|
dkrdnt
|
�
}
|d�|
�
S)z6
    Pull the body from the request and return it
    ZCONTENT_LENGTH�
0�r
z
wsgi.input)r
�int�read)�environ�lengthr
r
r�	read_body�s
r(c

CsV|�d
d�}
|
dkrt
dd��
z
tjj�t|�
�
WSty*
}
zt
d|��
d}~w
w)z)
    Return the request body as JSON
    ZCONTENT_TYPEr#�application/jsonrz
JSON requiredrN)r
r�salt�utils�json�loadsr(�
ValueError)r&�content_typer r
r
r�get_json�s






��r0cCs*d
tt
|�
�
i
}|
r|�|
�

t|���
S)z�
    Takes the response data as well as any additional headers and returns a
    tuple of tuples of headers suitable for passing to start_response()
    zContent-Length)�str�len�update�list�items)�dataZ
extra_headersZresponse_headersr
r
r�get_headers�s
�

r7ccs$�|d
}|
D]}|�|�
V
qdS)z]
    Expects a list of lowstate dictionaries that are executed and returned in
    order
    �SALT_APIClientN)
�run)r&Zlowstate�client�chunkr
r
r�	run_chunk�s
�
�r<c
Cs<|d
��}
|
dkrdS|
dkrt
|�
}t||�Stdd��
)z|
    Do any path/method dispatching here and return a JSON-serializable data
    structure appropriate for the response
    ZREQUEST_METHODZGETzFThey found me. I don't know how, but they found me. Run for it, Marty!�POSTrzMethod Not Allowed)�upperr0r<r)r&�methodr6r
r
r�dispatch�s





r@c
CsDd
t�v
rddl
}
|
j�tj�dd��
}||d<|
j�|�
|d<dS)zO
    Make Salt's opts dict and the APIClient available in the WSGI environ
    r	r
N�SALT_MASTER_CONFIG�/etc/salt/masterZ	SALT_OPTSr8)	�locals�salt.config�config�
client_configrr&r
ZnetapiZNetapiClient)r&r*r	r
r
r�saltenviron�s


�
rGc
Cs
t|�

z
t
t|�
�
}d
}WnIty'
}
z
|j}t|�
}WYd}~n5d}~w
tjjy@
}
zd}t|�
}WYd}~nd}~w
t	yW
}
zd}t|�
}WYd}~nd}~w
wztj
j�d|i
�
}Wnt
y{
}
zd}t|�
}WYd}~nd}~w
w|
t|t|ddi
��
|f
S)zp
    Process the request and return a JSON response. Catch errors and return the
    appropriate HTTP code.
    rNrr�returnzContent-Typer))rGr4r@rrr1r*�
exceptionsZEauthAuthenticationErrorrr+r,�dumps�	TypeError�
Hr7)r&Zstart_responseZresprr �retr
r
r�application
s4




�


�


��



��
rNc
Csd
dl}|j
�tj�dd��
S)z3
    Return the Salt master config as __opts__
    r
NrArB)rDrErFrr&r
)
r*r
r
r�get_opts(
s
�rOcCsvd
dlm
}
dt�v
rt�t�d<t�durtd�
�
t�ti�}
|d|
dt	�}z|�
�
WdSty:


td
�
�
w)	z
    Start simple_server()
    r
)
�make_serverr	F�
Z	localhostrN)Zwsgiref.simple_serverrP�globalsrOr�
SystemExitr	r
rrNZ
serve_forever�KeyboardInterrupt)rPrZhttpdr
r
r�start3
s






�rU�__main__)
N)rr�loggingrr*Zsalt.netapiZsalt.utils.jsonrLr�	getLogger�loggerrrrr!r(r0r7r<r@rGrNrOrUrr
r
r
r�<module>
s@{









�

	


"

�