File manager - Edit - /opt/saltstack/salt/lib/python3.10/site-packages/salt/netapi/rest_cherrypy/__pycache__/app.cpython-310.pyc
Back
o ;j:� � @ s~ d Z ddlZddlZddlZddlZddlZddlZddlZddlZddl m Z m Z ddl m Z mZ ddlmZ ddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZe� e �Z zddl m Z W n e!y� dZ e �"d� Y n e#y� dZ e �"d� Y nw zd d l$m%Z% d d l&m'Z' d Z(W n e#y� e)d e*fddi�Z'dZ(Y nw dd� Z+dd� Z,dd� Z-dd� Z.dd� Z/dd� Z0d ej1j2j3fd ej4ej1j5j6dd �ffZ7d d � Z8d!d"� Z9d#d$� Z:d%d&� Z;e:d'd(� �Z<e:d)d*� �Z=e:d+d,� �Z>d-d.� Z?d/d0� Z@d1e+fd2e,fgde0fd3e/fd.e?fgd0e@fd"e9fd4e.fgd5�ZAeA�B� D ]"\ZCZDeEeD�D ]\ZFZGeG\ZHZIeJej&eHejKeCeId6eF d7�� �q5�q-G d8d9� d9�ZLG d:d;� d;eL�ZMG d<d=� d=eL�ZNG d>d?� d?eL�ZOG d@dA� dAeL�ZPG dBdC� dCeL�ZQG dDdE� dEeL�ZRG dFdG� dGeL�ZSG dHdI� dI�ZTG dJdK� dK�ZUG dLdM� dM�ZVG dNdO� dO�ZWG dPdQ� dQ�ZXG dRdS� dS�ZYdTdU� ZZdS )VamR A REST API for Salt =================== .. py:currentmodule:: salt.netapi.rest_cherrypy.app .. note:: This module is Experimental on Windows platforms and supports limited configurations: - doesn't support PAM authentication (i.e. external_auth: auto) - doesn't support SSL (i.e. disable_ssl: True) :depends: - CherryPy Python module. Note: there is a `known SSL traceback for CherryPy versions 3.2.5 through 3.7.x <https://github.com/cherrypy/cherrypy/issues/1298>`_. Please use version 3.2.3 or the latest 10.x version instead. :optdepends: - ws4py Python module for websockets support. :client_libraries: - Java: https://github.com/SUSE/salt-netapi-client - Python: https://github.com/saltstack/pepper :setup: All steps below are performed on the machine running the Salt Master daemon. Configuration goes into the Master configuration file. 1. Install ``salt-api``. (This step varies between OS and Linux distros. Some package systems have a split package, others include salt-api in the main Salt package. Ensure the ``salt-api --version`` output matches the ``salt --version`` output.) 2. Install CherryPy. (Read the version caveat in the section above.) 3. Optional: generate self-signed SSL certificates. Using a secure HTTPS connection is strongly recommended since Salt eauth authentication credentials will be sent over the wire. 1. Install the PyOpenSSL package. 2. Generate a self-signed certificate using the :py:func:`~salt.modules.tls.create_self_signed_cert` execution function. .. code-block:: bash salt-call --local tls.create_self_signed_cert 4. Edit the master config to create at least one external auth user or group following the :ref:`full external auth instructions <acl-eauth>`. 5. Edit the master config with the following production-ready example to enable the ``rest_cherrypy`` module. (Adjust cert paths as needed, or disable SSL (not recommended!).) .. code-block:: yaml rest_cherrypy: port: 8000 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key 6. Restart the ``salt-master`` daemon. 7. Start the ``salt-api`` daemon. :configuration: All available configuration options are detailed below. These settings configure the CherryPy HTTP server and do not apply when using an external server such as Apache or Nginx. port **Required** The port for the webserver to listen on. host : ``0.0.0.0`` The socket interface for the HTTP server to listen on. debug : ``False`` Starts the web server in development mode. It will reload itself when the underlying code is changed and will output more debugging info. log_access_file Path to a file to write HTTP access logs. .. versionadded:: 2016.11.0 log_error_file Path to a file to write HTTP error logs. .. versionadded:: 2016.11.0 ssl_crt The path to a SSL certificate. (See below) ssl_key The path to the private key for your SSL certificate. (See below) ssl_chain (Optional when using PyOpenSSL) the certificate chain to pass to ``Context.load_verify_locations``. disable_ssl A flag to disable SSL. Warning: your Salt authentication credentials will be sent in the clear! webhook_disable_auth : False The :py:class:`Webhook` URL requires authentication by default but external services cannot always be configured to send authentication. See the Webhook documentation for suggestions on securing this interface. webhook_url : /hook Configure the URL endpoint for the :py:class:`Webhook` entry point. thread_pool : ``100`` The number of worker threads to start up in the pool. socket_queue_size : ``30`` Specify the maximum number of HTTP connections to queue. expire_responses : True Whether to check for and kill HTTP responses that have exceeded the default timeout. .. deprecated:: 2016.11.9,2017.7.3,2018.3.0 The "expire_responses" configuration setting, which corresponds to the ``timeout_monitor`` setting in CherryPy, is no longer supported in CherryPy versions >= 12.0.0. max_request_body_size : ``1048576`` Maximum size for the HTTP request body. collect_stats : False Collect and report statistics about the CherryPy server Reports are available via the :py:class:`Stats` URL. stats_disable_auth : False Do not require authentication to access the ``/stats`` endpoint. .. versionadded:: 2018.3.0 static A filesystem path to static HTML/JavaScript/CSS/image assets. static_path : ``/static`` The URL prefix to use when serving static assets out of the directory specified in the ``static`` setting. enable_sessions : ``True`` Enable or disable all endpoints that rely on session cookies. This can be useful to enforce only header-based authentication. .. versionadded:: 2017.7.0 app : ``index.html`` A filesystem path to an HTML file that will be served as a static file. This is useful for bootstrapping a single-page JavaScript app. Warning! If you set this option to a custom web application, anything that uses cookie-based authentication is vulnerable to XSRF attacks. Send the custom ``X-Auth-Token`` header instead and consider disabling the ``enable_sessions`` setting. .. versionchanged:: 2017.7.0 Add a proof-of-concept JavaScript single-page app. app_path : ``/app`` The URL prefix to use for serving the HTML file specified in the ``app`` setting. This should be a simple name containing no slashes. Any path information after the specified path is ignored; this is useful for apps that utilize the HTML5 history API. root_prefix : ``/`` A URL path to the main entry point for the application. This is useful for serving multiple applications from the same URL. .. _rest_cherrypy-auth: Authentication -------------- Authentication is performed by passing a session token with each request. Tokens are generated via the :py:class:`Login` URL. The token may be sent in one of two ways: as a custom header or as a session cookie. The latter is far more convenient for clients that support cookies. * Include a custom header named :mailheader:`X-Auth-Token`. For example, using curl: .. code-block:: bash curl -sSk https://localhost:8000/login \ -H 'Accept: application/x-yaml' \ -d username=saltdev \ -d password=saltdev \ -d eauth=pam Copy the ``token`` value from the output and include it in subsequent requests: .. code-block:: bash curl -sSk https://localhost:8000 \ -H 'Accept: application/x-yaml' \ -H 'X-Auth-Token: 697adbdc8fe971d09ae4c2a3add7248859c87079'\ -d client=local \ -d tgt='*' \ -d fun=test.ping * Sent via a cookie. This option is a convenience for HTTP clients that automatically handle cookie support (such as browsers). For example, using curl: .. code-block:: bash # Write the cookie file: curl -sSk https://localhost:8000/login \ -c ~/cookies.txt \ -H 'Accept: application/x-yaml' \ -d username=saltdev \ -d password=saltdev \ -d eauth=auto # Read the cookie file: curl -sSk https://localhost:8000 \ -b ~/cookies.txt \ -H 'Accept: application/x-yaml' \ -d client=local \ -d tgt='*' \ -d fun=test.ping Another example using the :program:`requests` library in Python: .. code-block:: python >>> import requests >>> session = requests.Session() >>> session.post('http://localhost:8000/login', json={ 'username': 'saltdev', 'password': 'saltdev', 'eauth': 'auto', }) <Response [200]> >>> resp = session.post('http://localhost:8000', json=[{ 'client': 'local', 'tgt': '*', 'fun': 'test.arg', 'arg': ['foo', 'bar'], 'kwarg': {'baz': 'Baz!'}, }]) >>> resp.json() {u'return': [{ ...snip... }]} .. seealso:: You can bypass the session handling via the :py:class:`Run` URL. Usage ----- This interface directly exposes Salt's :ref:`Python API <python-api>`. Everything possible at the CLI is possible through the Python API. Commands are executed on the Salt Master. The root URL (``/``) is RPC-like in that it accepts instructions in the request body for what Salt functions to execute, and the response contains the result of those function calls. For example: .. code-block:: text % curl -sSi https://localhost:8000 -H 'Content-type: application/json' -d '[{ "client": "local", "tgt": "*", "fun": "test.ping" }]' HTTP/1.1 200 OK Content-Type: application/json [...snip...] {"return": [{"jerry": true}]} The request body must be an array of commands. Use this workflow to build a command: 1. Choose a client interface. 2. Choose a function. 3. Fill out the remaining parameters needed for the chosen client. The ``client`` field is a reference to the main Python classes used in Salt's Python API. Read the full :ref:`Client APIs <client-apis>` documentation, but in short: * "local" uses :py:class:`LocalClient <salt.client.LocalClient>` which sends commands to Minions. Equivalent to the ``salt`` CLI command. * "runner" uses :py:class:`RunnerClient <salt.runner.RunnerClient>` which invokes runner modules on the Master. Equivalent to the ``salt-run`` CLI command. * "wheel" uses :py:class:`WheelClient <salt.wheel.WheelClient>` which invokes wheel modules on the Master. Wheel modules do not have a direct CLI equivalent but they typically manage Master-side resources such as state files, pillar files, the Salt config files, and the :py:mod:`key wheel module <salt.wheel.key>` exposes similar functionality as the ``salt-key`` CLI command. Most clients have variants like synchronous or asynchronous execution as well as others like batch execution. See the :ref:`full list of client interfaces <client-interfaces>`. Each client requires different arguments and sometimes has different syntax. For example, ``LocalClient`` requires the ``tgt`` argument because it forwards the command to Minions and the other client interfaces do not. ``LocalClient`` also takes ``arg`` (array) and ``kwarg`` (dictionary) arguments because these values are sent to the Minions and used to execute the requested function there. ``RunnerClient`` and ``WheelClient`` are executed directly on the Master and thus do not need or accept those arguments. Read the method signatures in the client documentation linked above, but hopefully an example will help illustrate the concept. This example causes Salt to execute two functions -- the :py:func:`test.arg execution function <salt.modules.test.arg>` using ``LocalClient`` and the :py:func:`test.arg runner function <salt.runners.test.arg>` using ``RunnerClient``; note the different structure for each command. The results for both are combined and returned as one response. .. code-block:: text % curl -b ~/cookies.txt -sSi localhost:8000 -H 'Content-type: application/json' -d ' [ { "client": "local", "tgt": "*", "fun": "test.arg", "arg": ["positional arg one", "positional arg two"], "kwarg": { "keyword arg one": "Hello from a minion", "keyword arg two": "Hello again from a minion" } }, { "client": "runner", "fun": "test.arg", "keyword arg one": "Hello from a master", "keyword arg two": "Runners do not support positional args" } ] ' HTTP/1.1 200 OK [...snip...] { "return": [ { "jerry": { "args": [ "positional arg one", "positional arg two" ], "kwargs": { "keyword arg one": "Hello from a minion", "keyword arg two": "Hello again from a minion", [...snip...] } }, [...snip; other minion returns here...] }, { "args": [], "kwargs": { "keyword arg two": "Runners do not support positional args", "keyword arg one": "Hello from a master" } } ] } One more example, this time with more commonly used functions: .. code-block:: text curl -b /tmp/cookies.txt -sSi localhost:8000 -H 'Content-type: application/json' -d ' [ { "client": "local", "tgt": "*", "fun": "state.sls", "kwarg": { "mods": "apache", "pillar": { "lookup": { "wwwdir": "/srv/httpd/htdocs" } } } }, { "client": "runner", "fun": "cloud.create", "provider": "my-ec2-provider", "instances": "my-centos-6", "image": "ami-1624987f", "delvol_on_destroy", true } ] ' HTTP/1.1 200 OK [...snip...] { "return": [ { "jerry": { "pkg_|-install_apache_|-httpd_|-installed": { [...snip full state return here...] } } [...snip other minion returns here...] }, { [...snip full salt-cloud output here...] } ] } Content negotiation ------------------- This REST interface is flexible in what data formats it will accept as well as what formats it will return (e.g., JSON, YAML, urlencoded). * Specify the format of data in the request body by including the :mailheader:`Content-Type` header. * Specify the desired data format for the response body with the :mailheader:`Accept` header. We recommend the JSON format for most HTTP requests. urlencoded data is simple and cannot express complex data structures -- and that is often required for some Salt commands, such as starting a state run that uses Pillar data. Salt's CLI tool can reformat strings passed in at the CLI into complex data structures, and that behavior also works via salt-api, but that can be brittle and since salt-api can accept JSON it is best just to send JSON. Here is an example of sending urlencoded data: .. code-block:: bash curl -sSik https://localhost:8000 \ -b ~/cookies.txt \ -d client=runner \ -d fun='jobs.lookup_jid' \ -d jid='20150129182456704682' .. admonition:: urlencoded data caveats * Only a single command may be sent per HTTP request. * Repeating the ``arg`` parameter multiple times will cause those parameters to be combined into a single list. Note, some popular frameworks and languages (notably jQuery, PHP, and Ruby on Rails) will automatically append empty brackets onto repeated query string parameters. E.g., ``?foo[]=fooone&foo[]=footwo``. This is **not** supported; send ``?foo=fooone&foo=footwo`` instead, or send JSON or YAML. A note about ``curl`` The ``-d`` flag to curl does *not* automatically urlencode data which can affect passwords and other data that contains characters that must be encoded. Use the ``--data-urlencode`` flag instead. E.g.: .. code-block:: bash curl -ksi http://localhost:8000/login \ -H "Accept: application/json" \ -d username='myapiuser' \ --data-urlencode password='1234+' \ -d eauth='pam' Performance Expectations and Recommended Usage ============================================== This module provides a thin wrapper around :ref:`Salt's Python API <python-api>`. Executing a Salt command via rest_cherrypy is directly analogous to executing a Salt command via Salt's CLI (which also uses the Python API) -- they share the same semantics, performance characteristics, and 98% of the same code. As a rule-of-thumb: if you wouldn't do it at the CLI don't do it via this API. Long-Running HTTP Connections ----------------------------- The CherryPy server is a production-ready, threading HTTP server written in Python. Because it makes use of a thread pool to process HTTP requests it is not ideally suited to maintaining large numbers of concurrent, synchronous connections. On moderate hardware with default settings it should top-out at around 30 to 50 concurrent connections. That number of long-running, synchronous Salt processes is also not ideal. Like at the CLI, each Salt command run will start a process that instantiates its own ``LocalClient``, which instantiates its own listener to the Salt event bus, and sends out its own periodic ``saltutil.find_job`` queries to determine if a Minion is still running the command. Not exactly a lightweight operation. Timeouts -------- In addition to the above resource overhead for long-running connections, there are the usual HTTP timeout semantics for the CherryPy server, any HTTP client being used, as well as any hardware in between such as proxies, gateways, or load balancers. rest_cherrypy can be configured not to time-out long responses via the ``expire_responses`` setting, and both :py:class:`LocalClient <salt.client.LocalClient>` and :py:class:`RunnerClient <salt.runner.RunnerClient>` have their own timeout parameters that may be passed as top-level keywords: .. code-block:: bash curl -b /tmp/cookies.txt -sSi localhost:8000 -H 'Content-type: application/json' -d ' [ { "client": "local", "tgt": "*", "fun": "test.sleep", "kwarg": {"length": 30}, "timeout": 60 }, { "client": "runner", "fun": "test.sleep", "kwarg": {"s_time": 30}, "timeout": 60 } ] ' Best Practices -------------- Given the performance overhead and HTTP timeouts for long-running operations described above, the most effective and most scalable way to use both Salt and salt-api is to run commands asynchronously using the ``local_async``, ``runner_async``, and ``wheel_async`` clients. Running asynchronous jobs results in being able to process 3x more commands per second for ``LocalClient`` and 17x more commands per second for ``RunnerClient``, in addition to much less network traffic and memory requirements. Job returns can be fetched from Salt's job cache via the ``/jobs/<jid>`` endpoint, or they can be collected into a data store using Salt's :ref:`Returner system <returners>`. The ``/events`` endpoint is specifically designed to handle long-running HTTP connections and it exposes Salt's event bus which includes job returns. Watching this endpoint first, then executing asynchronous Salt commands second, is the most lightweight and scalable way to use ``rest_cherrypy`` while still receiving job returns in real-time. But this requires clients that can properly handle the inherent asynchronicity of that workflow. Performance Tuning ------------------ The ``thread_pool`` and ``socket_queue_size`` settings can be used to increase the capacity of rest_cherrypy to handle incoming requests. Keep an eye on RAM usage as well as available file handles while testing changes to these settings. As salt-api is a thin wrapper around Salt's Python API, also keep an eye on the performance of Salt when testing. Future Plans ------------ Now that Salt uses the Tornado concurrency library internally, we plan to improve performance in the API by taking advantage of existing processes and event listeners and to use lightweight coroutines to facilitate more simultaneous HTTP connections and better support for synchronous operations. That effort can be tracked in `issue 26505`__, but until that issue is closed rest_cherrypy will remain the officially recommended REST API. .. __: https://github.com/saltstack/salt/issues/26505 .. |req_token| replace:: a session token from :py:class:`~Login`. .. |req_accept| replace:: the desired response format. .. |req_ct| replace:: the format of the request body. .. |res_ct| replace:: the format of the response body; depends on the :mailheader:`Accept` request header. .. |200| replace:: success .. |400| replace:: bad or malformed request .. |401| replace:: authentication required .. |406| replace:: requested Content-Type not available � N)�Iterator�Mapping)�Pipe�Process)� parse_qsl)�cpstatszjImport of cherrypy.cpstats failed. Possible upstream bug: https://github.com/cherrypy/cherrypy/issues/1444z"Import of cherrypy.cpstats failed.� )�event_processor)� websocketsTr �SynchronizingWebsocketFc C s� t jd } t j}| �dd�| �dd�f}dt jd vr dS |j�|�r%dS |j�d�d kr/dS z t jj� d �}W n t j yC Y dS w |d krJdS t � | �dd���) z� Bypass the normal handler and serve HTML for all URLs The ``app_path`` setting must be non-empty and the request must ask for ``text/html`` in the ``Accept`` header. �apiopts�app_pathz/app� static_path�/static�appNZAcceptz*/*z text/html) �cherrypy�config�request�get� path_info� startswith�headers�lib�cptools�accept� HTTPErrorZInternalRedirect)r r � url_blacklistZ wants_html� r �Q/opt/saltstack/salt/lib/python3.10/site-packages/salt/netapi/rest_cherrypy/app.py�html_override_tool� s& � �r c C s( t jj�dd�} | r| t jjd< dS dS )z� If the custom authentication header is supplied, put it in the cookie dict so the rest of the session-based auth works as intended � X-Auth-TokenN� session_id)r r r r �cookie)Zx_authr r r �salt_token_tool� s �r# c C s d}d}d}d}t j�dd�}|r |�dd�}|r |�dd�}|jj}|r�|�di �} | r~| | v rO|| | v s=d | | v rFt�|| |� d S t�|| |� d S | | vrud | v ru|| d v scd | d v rlt�|| |� d S t�|| |� d S t�|| |� d S dS t�|| |� d S ) a� .. versionadded:: 2016.3.0 Verifies user requests against the API whitelist. (User/IP pair) in order to provide whitelisting for the API similar to the master, but over the API. .. code-block:: yaml rest_cherrypy: api_acl: users: '*': - 1.1.1.1 - 1.1.1.2 foo: - 8.8.4.4 bar: - '*' :param username: Username to check against the API. :type username: str :param request: Cherrypy request to check against the API. :type request: cherrypy.request z6[api_acl] Authentication failed for user %s from IP %sz:[api_acl] Authentication successful for user %s from IP %sz;[api_acl] Authentication not checked for user %s from IP %sN�saltopts� rest_cherrypyZapi_acl�users�*TF)r r r Zremote�ip�logger�info) �usernamer Z failure_strZ success_strZpass_strZacl� salt_config� cherrypy_confr( r& r r r �salt_api_acl_tool� s< �r. c C s� t j�dd�} | r=| �dd�}|r?|�dd�}|rAt�d|� t jj�dd�}t�d|� ||vrCt�d|� t �d d ��dS dS dS dS ) zj If there is a list of restricted IPs, verify current client is coming from one of those IPs. r$ Nr% Zauthorized_ipszFound IP list: %sz Remote-AddrzRequest from IP: %szBlocked IP: %si� zBad IP) r r r r) �debugr r �errorr )r, r- Z auth_ip_listZrem_ipr r r �salt_ip_verify_tool� s �r1 c C s$ dt jvr t �d��dt jjd< dS )zA Redirect all unauthenticated requests to the login page �token� Zprivate� Cache-ControlN)r �sessionr �responser r r r r �salt_auth_tool s r7 c C s� t jj} t jj}| �dd�|d< d|d< d|d< t jjdkrd| �d d �}d d g}g d �}|rH||v rHd�|�|d< d�|�|d< d|d< d|d< dt j_dt j_d t j j_ t jj �dd�rbdt j d< dS d S )a Handle both simple and complex CORS requests Add CORS headers to each response. If the request is a CORS preflight request swap out the default handler with a simple, single-purpose handler that verifies the request and provides a valid CORS response. ZOriginr' zAccess-Control-Allow-Originz GET, POSTz Access-Control-Expose-Headers�truez Access-Control-Allow-CredentialsZOPTIONSz Access-Control-Request-MethodN�GET�POST)� Content-Typer zX-Requested-Withz, z Access-Control-Allow-Methodsz Access-Control-Allow-Headers� keep-alive� ConnectionZ1400zAccess-Control-Max-Age� �� �tools.sessions.onFTr2 ) r r r r6 r �method�join�body�status�serving�handlerr r5 )Zreq_headZ resp_headZ ac_methodZallowed_methodsZallowed_headersr r r � cors_tool s* �rG �application/json�application/x-yaml)Zdefault_flow_stylec O s� zt t�tj_tjjj| i |��}W n� tj j tj j tj j tj j fy7 } z t�|j� t�d|j��d}~w tj jyQ } z t�|j� t�d|j��d}~w tj jtj jfyi } zt�d|j��d}~w tj jyv t�d�� tjy~ � ty� } z9ttd�r�t|tj�r�t�d��ddl }tj dtjj d d � d tj_ tjj tj d r�|�!� � nd d�}W Y d}~nd}~ww tj"j#�$dd� tD ��}|tjj%d< tjj| }z ||�}tj&j'�(|�W S ty� d} tj | d d � t�d | ��w )a, Determine the best output format based on the Accept header, execute the regular handler, and transform the output to the request content type (even if it's an error). :param args: Pass args through to the main handler :param kwargs: Pass kwargs through to the main handler r3 N� i� i� � TimeoutErrorr z&Error while processing request for: %sT��exc_infoi� r/ z An unexpected error occurred�rD �returnc S s g | ]\}}|�qS r r )�.0�i�_r r r � <listcomp>� s z&hypermedia_handler.<locals>.<listcomp>r; z.Could not serialize the return data from Salt.))�dict� ct_out_mapr r6 � processorsrE r �_hypermedia_inner_handler�salt� exceptionsZAuthenticationErrorZAuthorizationErrorZEauthAuthenticationErrorZTokenAuthenticationErrorr) r0 �messager ZSaltInvocationError�SaltDaemonNotRunningZSaltReqTimeoutError�strerrorZSaltClientTimeoutZCherryPyException� Exception�hasattr� isinstancerK � tracebackr/ r rD r � format_excr r r r �utils� stringutils�to_bytes) �args�kwargs�ret�e�excr` Zbest�outr6 �msgr r r �hypermedia_handlerN sl � � � �� � ���� �rl c C s( t jj} | j| _| jdurt| _dS dS )z� Determine the best handler for the requested content type Wrap the normal handler and transform the output from that handler into the requested content type N)r rE r rF rW rl )r r r r �hypermedia_out� s �rm c s t �� �� fdd��}|S )zS A decorator to skip a processor function if process_request_body is False c s" t jjdur� | i |�� d S d S )NF)r r �process_request_body)re rf ��fnr r �wrapped� s �z%process_request_body.<locals>.wrapped)� functools�wraps)rp rq r ro r rn � s rn c C s& | � � }z|�d�}W n ttfy Y nw |tjj_i }t|�D ] \}}|� |g �� |� q"|� � D ]\}}t |�dkrD|d ||< t |�dkrNd||< q4d|v r^t jj�|d �|d< d|v r�t|d t�r�t|d �D ]\}}t jj�|�|d |< qon t jj�|d �g|d< |tjj_dS )a� Accept x-www-form-urlencoded data and reformat it into a Low State data structure. Since we can't easily represent complicated data structures with key-value pairs, any more complicated requirements (e.g. compound commands) must instead be delivered via JSON or YAML. For example:: .. code-block:: bash curl -si localhost:8000 -d client=local -d tgt='*' \ -d fun='test.kwarg' -d arg='one=1' -d arg='two=2' :param entity: raw POST data �utf-8r r � �kwarg�argN)�read�decode�UnicodeDecodeError�AttributeErrorr rE r �raw_bodyr � setdefault�append�items�lenrX rb re Z yamlify_argr_ �list� enumerate�unserialized_data)�entityZ urlencodedr� �key�val�idx�valuer r r �urlencoded_processor� s8 � ����r� c C sv t �� }| jj|d�}|�d� tjj�|�� �}~z tjj � |�t j j _W n ty3 t �dd��w |t j j _dS )zp Unserialize raw POST data in JSON format to a Python data structure. :param entity: raw POST data �Zfp_outr rJ zInvalid JSON documentN)�io�BytesIO�fprx �seekrX rb rc � to_unicode�json�loadsr rE r r� � ValueErrorr r| �r� �contentsrC r r r �json_processor� s �r� c C st t �� }| jj|d�}|�d� tjj�|�� �}z tjj � |�t j j _W n ty2 t �dd��w |t j j _dS )zp Unserialize raw POST data in YAML format to a Python data structure. :param entity: raw POST data r� r rJ zInvalid YAML documentN)r� r� r� rx r� rX rb rc r� �yamlZ safe_loadr rE r r� r� r r| r� r r r �yaml_processor� s �r� c C sv t �� }| jj|d�}|�d� tjj�|�� �}z tjj � |�t j j _W n ty3 |t j j _Y nw |t j j _dS )z� Attempt to unserialize plain text as JSON Some large services still send JSON with a text/plain Content-Type. Those services are bad and should feel bad. :param entity: raw POST data r� r N)r� r� r� rx r� rX rb rc r� r� r� r rE r r� r� r| r� r r r �text_processor s �r� c C sr t ttttd�} tjj�� dkr"tjj� dd�dkr"dtj_ dtj_ tjj j �� t�dd�tjj _| tjj _ dS ) a: Unserialize POST/PUT data of a specified Content-Type. The following custom processors all are intended to format Low State data and will place that data structure into the request object. :raises HTTPError: if the request contains a Content-Type that we do not have a processor for )z!application/x-www-form-urlencodedrH rI z text/yamlz text/plainr: �Content-Length�0FNi� zContent type not supported)r� r� r� r� r r rA �upperr r rn r� rC rV �clearr Z default_proc)Z ct_in_mapr r r � hypermedia_in* s � �r� c C sj t jj�� dkr dS t jj} | r.t| t�r.d| v r't| d t�s'| d g| d< | gt j_dS | t j j_dS )z� Validate and format lowdata from incoming unserialized request data This tool requires that the hypermedia_in tool has already been run. r: Nrw ) r r rA r� r� r_ r r� �lowstaterE )�datar r r � lowdata_fmtM s �r� Z html_override� salt_token� salt_authZsalt_ip_verify)Zon_start_resourceZbefore_request_bodyZbefore_handler�2 )�priorityc @ sr e Zd ZdZdZdddddddd�Zdd� Zddd �Zej di d d i��d d � �Z ej � � ej � � dd� ��ZdS )�LowDataAdapterz5 The primary entry point to Salt's REST API TiX )ztools.salt_token.onr@ ztools.sessions.timeout�tools.hypermedia_out.on�tools.hypermedia_in.on�tools.lowdata_fmt.onztools.salt_ip_verify.onc C s t jd | _t jd | _d S �Nr$ r )r r �optsr ��selfr r r �__init__� s zLowDataAdapter.__init__Nc c sN � t jj}t jj�dd�rt j�� t|t�s t � dd��t j � | j ��y}|D ]m}|r/||d< d|v rLz t|d d� W n ttfyK t � dd��w d|v riz t|d d� W n ttfyh t � dd��w |ro||d < d |v r�t|d t�s�|d g|d < |�|�}t|t�r�|E d H q'|V q'W d � d S 1 s�w Y d S ) z� Pull a Low State data structure from request and execute the low-data chunks through Salt. The low-data chunks will be updated to include the authorization token for the current session. r@ FrJ zLowstates must be a listr2 � r3 z Invalid token�clientrw N)r r r� r r r5 � release_lockr_ r� r rX �netapi� NetapiClientr� �int� TypeErrorr� �runr )r� r� r2 r� �api�chunkrg r r r � exec_lowstate� s@ � � � �"�z LowDataAdapter.exec_lowstater@ Fc C s dt jjd�S )aS An explanation of the API with links of where to go next .. http:get:: / :reqheader Accept: |req_accept| :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -i localhost:8000 .. code-block:: text GET / HTTP/1.1 Host: localhost:8000 Accept: application/json **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Type: application/json ZWelcome)rO Zclients)rX r� ZCLIENTSr� r r r r9 � s !�zLowDataAdapter.GETc K s dt | jtj�d�d��iS )a� Send one or more Salt commands in the request body .. http:post:: / :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :reqheader Content-Type: |req_ct| :resheader Content-Type: |res_ct| :status 200: |200| :status 400: |400| :status 401: |401| :status 406: |406| :term:`lowstate` data describing Salt commands must be sent in the request body. **Example request:** .. code-block:: bash curl -sSik https://localhost:8000 \ -b ~/cookies.txt \ -H "Accept: application/x-yaml" \ -H "Content-type: application/json" \ -d '[{"client": "local", "tgt": "*", "fun": "test.ping"}]' .. code-block:: text POST / HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml X-Auth-Token: d40d1e1e Content-Type: application/json [{"client": "local", "tgt": "*", "fun": "test.ping"}] **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 200 Allow: GET, HEAD, POST Content-Type: application/x-yaml return: - ms-0: true ms-1: true ms-2: true ms-3: true ms-4: true rO r2 �r2 )r� r� r r5 r �r� rf r r r r: � s :zLowDataAdapter.POST)NNr )�__name__� __module__� __qualname__�__doc__�exposed� _cp_configr� r� r r r9 �toolsr� r� r: r r r r r� � s$ � 7 $r� c @ s8 e Zd ZdZeejfi ddi��Zd dd�Zdd� ZdS ) �Minionsz3 Convenience URLs for working with minions �tools.salt_auth.onTNc C s2 d|pddd�gt j_dt| jt j�d�d��iS )aH A convenience URL for getting lists of minions or getting minion details .. http:get:: /minions/(mid) :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -i localhost:8000/minions/ms-3 .. code-block:: text GET /minions/ms-3 HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 129005 Content-Type: application/x-yaml return: - ms-3: grains.items: ... �localr' z grains.items)r� Ztgt�funrO r2 r� )r r r� r� r� r5 r )r� �midr r r r9 < s (��z Minions.GETc K s: t | jdtj�d�d��}dtj_|ddd� |D �id�S ) a� Start an execution command and immediately return the job id .. http:post:: /minions :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :reqheader Content-Type: |req_ct| :resheader Content-Type: |res_ct| :status 200: |200| :status 400: |400| :status 401: |401| :status 406: |406| Lowstate data describing Salt commands must be sent in the request body. The ``client`` option will be set to :py:meth:`~salt.client.LocalClient.local_async`. **Example request:** .. code-block:: bash curl -sSi localhost:8000/minions \ -b ~/cookies.txt \ -H "Accept: application/x-yaml" \ -d '[{"tgt": "*", "fun": "status.diskusage"}]' .. code-block:: text POST /minions HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml Content-Type: application/x-www-form-urlencoded tgt=*&fun=status.diskusage **Example response:** .. code-block:: text HTTP/1.1 202 Accepted Content-Length: 86 Content-Type: application/x-yaml return: - jid: '20130603122505459265' minions: [ms-4, ms-3, ms-2, ms-1, ms-0] _links: jobs: - href: /jobs/20130603122505459265 Z local_asyncr2 )r� r2 �� �jobsc S s" g | ] }|rd d� |d �i�qS )Zhrefz/jobs/{}�jid)�format)rP rQ r r r rS � s " z Minions.POST.<locals>.<listcomp>)rO Z_links)r� r� r r5 r r6 rD )r� rf Zjob_datar r r r: j s 6 ����z Minions.POST�N) r� r� r� r� rT r� r� r9 r: r r r r r� 5 s .r� c @ s, e Zd Zeejfi ddi��Zddd�ZdS )�Jobsr� TNru c C s� ddi}|r|� d|d�� n|� ddi� |gtj_t| jtj�d�d��}i }|r`|d g|d < i }|d �d �}|D ]}d || v rO|| �d �||< q=|| �d �||< q=|g|d < |S |d g|d < |S ) a� A convenience URL for getting lists of previously run jobs or getting the return from a single job .. http:get:: /jobs/(jid) List jobs or show a single job from the job cache. :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -i localhost:8000/jobs .. code-block:: text GET /jobs HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 165 Content-Type: application/x-yaml return: - '20121130104633606931': Arguments: - '3' Function: test.fib Start Time: 2012, Nov 30 10:46:33.606931 Target: jerry Target-type: glob **Example request:** .. code-block:: bash curl -i localhost:8000/jobs/20121130104633606931 .. code-block:: text GET /jobs/20121130104633606931 HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 73 Content-Type: application/x-yaml info: - Arguments: - '3' Function: test.fib Minions: - jerry Start Time: 2012, Nov 30 10:46:33.606931 Target: '*' Target-type: glob User: saltdev jid: '20121130104633606931' return: - jerry: - - 0 - 1 - 1 - 2 - 6.9141387939453125e-06 r� �runnerz jobs.list_job)r� r� r� zjobs.list_jobsr2 r� r r* ZResultrO )�updater r r� r� r� r5 r ) r� r� �timeoutr� Z job_ret_inforg Z minion_ret�returnsZminionr r r r9 � s& T �zJobs.GET)Nru )r� r� r� rT r� r� r9 r r r r r� � s r� c @ s8 e Zd ZdZd dd�Zejd i ddd���dd� �ZdS ) �Keysz� Convenience URLs for working with minion keys .. versionadded:: 2014.7.0 These URLs wrap the functionality provided by the :py:mod:`key wheel module <salt.wheel.key>` functions. Nc C sZ |r dd|d�g}nddd�g}|t j_| jt j�d�d�}dt|i ��d i ��di �iS ) a� Show the list of minion keys or detail on a specific key .. versionadded:: 2014.7.0 .. http:get:: /keys/(mid) List all keys or show a specific key :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -i localhost:8000/keys .. code-block:: text GET /keys HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 165 Content-Type: application/x-yaml return: local: - master.pem - master.pub minions: - jerry minions_pre: [] minions_rejected: [] **Example request:** .. code-block:: bash curl -i localhost:8000/keys/jerry .. code-block:: text GET /keys/jerry HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 73 Content-Type: application/x-yaml return: minions: jerry: 51:93:b3:d0:9f:3a:6d:e5:28:67:c2:4b:27:d6:cd:2b �wheelz key.finger)r� r� �matchz key.list_all�r� r� r2 r� rO r� )r r r� r� r5 r �next)r� r� r� �resultr r r r9 * s F zKeys.GETF)r� r@ c K sB t jj}|d �ddd�� d|d v r |d �d�|d d< | �� }t|i ��di ��di �}|�d d �}t� d �}t |�|_ |�d d �}t� d �}t |�|_ t � � } tj| dd�} |�t�}|�t�}| �|t � |�� | �|t � |�� | �� t jj} d�|d d �| d< d| d< t | �� �| d< d| d< | �d� | S )a� Easily generate keys for a minion and auto-accept the new key Accepts all the same parameters as the :py:func:`key.gen_accept <salt.wheel.key.gen_accept>`. .. note:: A note about ``curl`` Avoid using the ``-i`` flag or HTTP headers will be written and produce an invalid tar file. Example partial kickstart script to bootstrap a new minion: .. code-block:: text %post mkdir -p /etc/salt/pki/minion curl -sSk https://localhost:8000/keys \ -d mid=jerry \ -d username=kickstart \ -d password=kickstart \ -d eauth=pam \ | tar -C /etc/salt/pki/minion -xf - mkdir -p /etc/salt/minion.d printf 'master: 10.0.0.5\nid: jerry' > /etc/salt/minion.d/id.conf %end .. http:post:: /keys Generate a public and private key and return both as a tarball Authentication credentials must be passed in the request. :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -sSk https://localhost:8000/keys \ -d mid=jerry \ -d username=kickstart \ -d password=kickstart \ -d eauth=pam \ -o jerry-salt-keys.tar .. code-block:: text POST /keys HTTP/1.1 Host: localhost:8000 **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 10240 Content-Disposition: attachment; filename="saltkeys-jerry.tar" Content-Type: application/x-tar jerry.pub0000644000000000000000000000070300000000000010730 0ustar 00000000000000 r r� zkey.gen_acceptr� r� Zid_r� rO Zpubru z minion.pubZprivz minion.pem�w)�fileobj�modez&attachment; filename="saltkeys-{}.tar"zContent-Dispositionzapplication/x-tarr; r� �no-cacher4 )r r r� r� �popr� r� r �tarfile�TarInfor� �sizer� r� �open�encodeZ__salt_system_encoding__�addfile�closer6 r r� �getvaluer� ) r� rf r� r� rg Zpub_keyZ pub_key_fileZpriv_keyZ priv_key_filer� Ztarballr r r r r: z s6 B � z Keys.POSTr� r )r� r� r� r� r9 r r r: r r r r r� s Pr� c s0 e Zd ZdZ� fdd�Zdd� Zdd� Z� ZS )�Loginzh Log in to receive a session token :ref:`Authentication information <rest_cherrypy-auth>`. c s& t � j|i |�� tj�| j�| _d S r� )�superr� rX �auth�Resolverr� )r� re rf �� __class__r r r� � s zLogin.__init__c C s dt jjd< t jjdd�S )a9 Present the login interface .. http:get:: /login An explanation of how to log in. :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -i localhost:8000/login .. code-block:: text GET /login HTTP/1.1 Host: localhost:8000 Accept: text/html **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Type: text/html ZSessionzWWW-Authenticatez Please log inrN )r r6 r rD r� r r r r9 � s �z Login.GETc K s� t j�| j��}|�� st j�d��W d � n1 s w Y ttj j j t �r1tj j j d }ntj j j }|� dd�}t|tj �sGt�d��| j�|�}d|vrWt�dd��tjjtjjd< |d tjd< |d |d d tjd < zA| j� d i �� |d i �}|d dkr�d|v r�|d }n |d dkr�d|v r�|d }n t j�||�}t j�|�}|s�t�d� W n ty� tjd|� d�|� d�dd� d}Y nw dtjj|d |d |d |d |p�i d�giS )aU :ref:`Authenticate <rest_cherrypy-auth>` against Salt's eauth system .. http:post:: /login :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :reqheader Content-Type: |req_ct| :form eauth: the eauth backend configured for the user :form username: username :form password: password :status 200: |200| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -si localhost:8000/login \ -c ~/cookies.txt \ -H "Accept: application/json" \ -H "Content-type: application/json" \ -d '{ "username": "saltuser", "password": "saltuser", "eauth": "auto" }' .. code-block:: text POST / HTTP/1.1 Host: localhost:8000 Content-Length: 42 Content-Type: application/json Accept: application/json {"username": "saltuser", "password": "saltuser", "eauth": "auto"} **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Type: application/json Content-Length: 206 X-Auth-Token: 6d1b722e Set-Cookie: session_id=6d1b722e; expires=Sat, 17 Nov 2012 03:23:52 GMT; Path=/ {"return": { "token": "6d1b722e", "start": 1363805943.776223, "expire": 1363849143.776224, "user": "saltuser", "eauth": "pam", "perms": [ "grains.*", "status.*", "sys.*", "test.*" ] }} z Salt Master is not available.Nr r+ r3 r2 z1Could not authenticate using provided credentialsr �expire�start�< r� Z external_auth�eauthZdjangoz^modelZ auth_list�restz Eauth permission list not found.zDConfiguration for external_auth malformed for eauth %r, and user %r.�nameTrL rO )r2 r� r� �userr� �perms)rX r� r� r� Z_is_master_runningrY r[ r_ r rE r r� r� r r. r r� Zmk_tokenr5 �idr6 r Zsum_permissionsZsorted_permissionsr) r/ r] )r� rf r� �credsr+ r2 r� r� r r r r: sf C�� � � � �� ���z Login.POST)r� r� r� r� r� r9 r: � __classcell__r r r� r r� � s &r� c @ s0 e Zd ZdZeejfi ddd���Zdd� ZdS )�Logoutz0 Class to remove or invalidate sessions TF)r� r� c C s t jj�� t j�� ddiS )zT Destroy the currently active session and expire the session cookie rO zYour token has been cleared)r r Zsessionsr� r5 Z regenerater� r r r r: � s z Logout.POSTN�r� r� r� r� rT r� r� r: r r r r r� � s �� r� c @ s, e Zd ZdZejdi ddi��dd� �ZdS )�Tokenz� Generate a Salt token from eauth credentials Wraps functionality in the :py:mod:`auth Runner <salt.runners.auth>`. .. versionadded:: 2017.7.0 r@ Fc K s^ t jjD ]$}z|�dd|d |d |d d�d�� W q ty( t �dd ��w t| �� �S ) ae .. http:post:: /token Generate a Salt eauth token :status 200: |200| :status 400: |400| :status 401: |401| **Example request:** .. code-block:: bash curl -sSk https://localhost:8000/token \ -H 'Content-type: application/json' \ -d '{ "username": "saltdev", "password": "saltdev", "eauth": "auto" }' **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Type: application/json [{ "start": 1494987445.528182, "token": "e72ca1655d05...", "expire": 1495030645.528183, "name": "saltdev", "eauth": "auto" }] r� z auth.mk_tokenr+ �passwordr� )r+ r� r� )r� r� rv rJ z2Require "username", "password", and "eauth" params)r r r� r� �KeyErrorr r� r� )r� rf r� r r r r: � s" &��� �� z Token.POSTNr )r� r� r� r� r r r: r r r r r� � s r� c @ s. e Zd ZdZeejfi ddi��Zdd� ZdS )�Runa8 Run commands bypassing the :ref:`normal session handling <rest_cherrypy-auth>`. salt-api does not enforce authorization, Salt's eauth system does that. Local/Runner/WheelClient all accept ``username``/``password``/``eauth`` **or** ``token`` kwargs that are then checked by the eauth system. The session mechanism in ``rest_cherrypy`` simply pairs a session with a Salt eauth token and then passes the ``token`` kwarg in automatically. If you already have a Salt eauth token, perhaps generated by the :py:func:`mk_token <salt.runners.auth.mk_token>` function in the Auth Runner module, then there is no reason to use sessions. This endpoint accepts either a ``username``, ``password``, ``eauth`` trio, **or** a ``token`` kwarg and does not make use of sessions at all. r@ Fc K s dt | �� �iS )a� Run commands bypassing the :ref:`normal session handling <rest_cherrypy-auth>`. Otherwise, this URL is identical to the :py:meth:`root URL (/) <LowDataAdapter.POST>`. .. http:post:: /run An array of lowstate data describing Salt commands must be sent in the request body. :status 200: |200| :status 400: |400| :status 401: |401| :status 406: |406| **Example request:** .. code-block:: bash curl -sS localhost:8000/run \ -H 'Accept: application/x-yaml' \ -H 'Content-type: application/json' \ -d '[{ "client": "local", "tgt": "*", "fun": "test.ping", "username": "saltdev", "password": "saltdev", "eauth": "auto" }]' **Or** using a Salt Eauth token: .. code-block:: bash curl -sS localhost:8000/run \ -H 'Accept: application/x-yaml' \ -H 'Content-type: application/json' \ -d '[{ "client": "local", "tgt": "*", "fun": "test.ping", "token": "<salt eauth token here>" }]' .. code-block:: text POST /run HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml Content-Length: 75 Content-Type: application/json [{"client": "local", "tgt": "*", "fun": "test.ping", "username": "saltdev", "password": "saltdev", "eauth": "auto"}] **Example response:** .. code-block:: text HTTP/1.1 200 OK Content-Length: 73 Content-Type: application/x-yaml return: - ms-0: true ms-1: true ms-2: true ms-3: true ms-4: true The /run endpoint can also be used to issue commands using the salt-ssh subsystem. When using salt-ssh, eauth credentials must also be supplied, and are subject to :ref:`eauth access-control lists <acl>`. All SSH client requests are synchronous. **Example SSH client request:** .. code-block:: bash curl -sS localhost:8000/run \ -H 'Accept: application/x-yaml' \ -d client='ssh' \ -d tgt='*' \ -d username='saltdev' \ -d password='saltdev' \ -d eauth='auto' \ -d fun='test.ping' .. code-block:: text POST /run HTTP/1.1 Host: localhost:8000 Accept: application/x-yaml Content-Length: 75 Content-Type: application/x-www-form-urlencoded **Example SSH response:** .. code-block:: text return: - silver: _stamp: '2020-09-08T23:04:28.912609' fun: test.ping fun_args: [] id: silver jid: '20200908230427905565' retcode: 0 return: true rO )r� r� r� r r r r: s q�zRun.POSTNr� r r r r r� � s r� c @ sJ e Zd ZdZdZeejfi dddddd���Zdd� Zdd � Z d d � Z d S ) �EventsaK Expose the Salt event bus The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real-time window into a running Salt infrastructure. .. seealso:: :ref:`events` Trt F)�response.stream�tools.encode.encodingr� r� r� c C s t jd | _tj�| j�| _d S �Nr$ )r r r� rX r� r� �resolverr� r r r r� � � zEvents.__init__c C s| zt |d� W n ttfy Y dS w tjj�|i df�\}}|�d|�}|r<| j�|�}|r<|�dd�t � � kr<dS dS )a Check if this is a valid salt-api token or valid Salt token salt-api tokens are regular session tokens that tie back to a real Salt token. Salt tokens are tokens generated by Salt's eauth system. :return bool: True if valid, False if not valid. r� FNr2 r� r T) r� r� r� r r5 �cacher r� Z get_token�time)r� � auth_token� orig_sessionrR r� Z resolved_tknr r r �_is_valid_token� s � zEvents._is_valid_tokenc s� |rt �dd��t jj}t jj�d�p d|v r |d jnd� ��� �s(t �d��t j� � dt j jd< d t j jd < d t j jd < � �fd d�}|� S )a� An HTTP stream of the Salt master event bus This stream is formatted per the Server Sent Events (SSE) spec. Each event is formatted as JSON. .. http:get:: /events :status 200: |200| :status 400: |400| -- the endpoint takes no query parameters; in particular tokens must not be passed in the URL. :status 401: |401| :status 406: |406| Authentication channels: - ``X-Auth-Token`` header (the recommended path for non-browser clients -- ``curl``, scripts, server-side integrations). - Session cookie set by ``/login`` (the recommended path for browser ``EventSource`` clients, which the EventSource API does not let you set custom headers on). Tokens passed via the query string (``?token=...`` or ``?salt_token=...``) used to be accepted as a workaround for the browser EventSource API. They are no longer accepted: the URL ends up in HTTP access logs, the browser ``Referer`` header, log-aggregation pipelines, and error reports, none of which are appropriate channels for a bearer credential. Use the cookie path instead -- log in via ``/login`` first, the cookie is sent automatically when the EventSource opens. **Example request (non-browser client):** .. code-block:: bash curl -NsS -H "X-Auth-Token: <token>" localhost:8000/events .. code-block:: text GET /events HTTP/1.1 Host: localhost:8000 X-Auth-Token: <token> **Example response:** Note, the ``tag`` field is not part of the spec. SSE compliant clients should ignore unknown fields. This addition allows non-compliant clients to only watch for certain tags without having to deserialze the JSON object each time. .. code-block:: text HTTP/1.1 200 OK Connection: keep-alive Cache-Control: no-cache Content-Type: text/event-stream;charset=utf-8 retry: 400 tag: salt/job/20130802115730568475/new data: {'tag': 'salt/job/20130802115730568475/new', 'data': {'minions': ['ms-4', 'ms-3', 'ms-2', 'ms-1', 'ms-0']}} tag: salt/job/20130802115730568475/ret/jerry data: {'tag': 'salt/job/20130802115730568475/ret/jerry', 'data': {'jid': '20130802115730568475', 'return': True, 'retcode': 0, 'success': True, 'cmd': '_return', 'fun': 'test.ping', 'id': 'ms-1'}} The event stream can be easily consumed via JavaScript: .. code-block:: javascript var source = new EventSource('/events'); source.onopen = function() { console.info('Listening ...') }; source.onerror = function(err) { console.error(err) }; source.onmessage = function(message) { var saltEvent = JSON.parse(message.data); console.log(saltEvent.tag, saltEvent.data); }; Note, the SSE stream is fast and completely asynchronous and Salt is very fast. If a job is created using a regular POST request, it is possible that the job return will be available on the SSE stream before the response for the POST request arrives. It is important to take that asynchronicity into account when designing an application. Below are some general guidelines. * Subscribe to the SSE stream _before_ creating any events. * Process SSE events directly as they arrive and don't wait for any other process to "complete" first (like an ajax request). * Keep a buffer of events if the event stream must be used for synchronous lookups. * Be cautious in writing Salt's event stream directly to the DOM. It is very busy and can quickly overwhelm the memory allocated to a browser tab. A full, working proof-of-concept JavaScript application is available :blob:`adjacent to this file <salt/netapi/rest_cherrypy/index.html>`. It can be viewed by pointing a browser at the ``/app`` endpoint in a running ``rest_cherrypy`` instance. For cross-origin EventSource, set ``withCredentials`` and rely on the session cookie established by ``/login`` rather than a query-string token: .. code-block:: javascript var source = new EventSource('/events', {withCredentials: true}); It is also possible to consume the stream via the shell. Records are separated by blank lines; the ``data:`` and ``tag:`` prefixes will need to be removed manually before attempting to unserialize the JSON. curl's ``-N`` flag turns off input buffering which is required to process the stream incrementally. Here is a basic example of printing each event as it comes in: .. code-block:: bash curl -NsS -H "X-Auth-Token: <token>" localhost:8000/events |\ while IFS= read -r line ; do echo $line done Here is an example of using awk to filter events based on tag: .. code-block:: bash curl -NsS -H "X-Auth-Token: <token>" localhost:8000/events |\ awk ' BEGIN { RS=""; FS="\\n" } $1 ~ /^tag: salt\/job\/[0-9]+\/new$/ { print $0 } ' tag: salt/job/20140112010149808995/new data: {"tag": "salt/job/20140112010149808995/new", "data": {"tgt_type": "glob", "jid": "20140112010149808995", "tgt": "jerry", "_stamp": "2014-01-12_01:01:49.809617", "user": "shouse", "arg": [], "fun": "test.ping", "minions": ["jerry"]}} tag: 20140112010149808995 data: {"tag": "20140112010149808995", "data": {"fun_args": [], "jid": "20140112010149808995", "return": true, "retcode": 0, "success": true, "cmd": "_return", "_stamp": "2014-01-12_01:01:49.819316", "fun": "test.ping", "id": "jerry"}} rJ a* The /events endpoint takes no query parameters; in particular, tokens must not be passed via the query string -- they end up in access logs and the Referer header. Use the 'X-Auth-Token' header (for non-browser clients) or the session cookie set by /login (for browser EventSource clients) instead.r r! Nr3 ztext/event-streamr; r� r4 r< r= c 3 s� � t jjjd�jd �jdd��:} | jddd�}dV ��� �s't�d� nt |�}d� |� d d ��V d t jj � |�� d �V q W d � d S 1 sMw Y d S )z: An iterator to yield Salt events �master�sock_dirT�r r� �listen��fullZauto_reconnectz retry: 400 zToken is no longer validztag: {} �tagru �data: � N)rX rb �event� get_eventr� � iter_eventsr r) r/ r� r� r r� �dumps)r �streamr� �r r� r r r j s( �� �"�zEvents.GET.<locals>.listen) r r r r" r r r� r r5 r� r6 )r� rf Zcookiesr r r r r9 � s$ � � z Events.GETN) r� r� r� r� r� rT r� r� r� r r9 r r r r r� { s ��� !r� c @ sJ e Zd ZdZdZeejfi ddddddej d���Zdd� Z d d d �Z dS ) �WebsocketEndpointa� Open a WebSocket connection to Salt's event bus The event bus on the Salt master exposes a large variety of things, notably when executions are started on the master and also when minions ultimately return their results. This URL provides a real-time window into a running Salt infrastructure. Uses websocket as the transport mechanism. .. seealso:: :ref:`events` Trt F)r� r� r� r� r� ztools.websocket.onztools.websocket.handler_clsc C s t jd | _tj�| j�| _d S r� )r r r� rX r� ZLoadAuthr� r r r r� � r zWebsocketEndpoint.__init__Nc s� |rt jj�|i df�\}}|�d��nt j�d���r"�j���s't �d��t j�� t jj }� ��fdd�}t � \}}||_ �j |_ t |||fd�} | �� dS )a� Return a websocket connection of Salt's event stream .. http:get:: /ws/(token) :query format_events: The event stream will undergo server-side formatting if the ``format_events`` URL parameter is included in the request. This can be useful to avoid formatting on the client-side: .. code-block:: bash curl -NsS <...snip...> localhost:8000/ws?format_events :reqheader X-Auth-Token: an authentication token from :py:class:`~Login`. :status 101: switching to the websockets protocol :status 401: |401| :status 406: |406| **Example request:** :: curl -NsSk \ -H 'X-Auth-Token: ffedf49d' \ -H 'Host: localhost:8000' \ -H 'Connection: Upgrade' \ -H 'Upgrade: websocket' \ -H 'Origin: https://localhost:8000' \ -H 'Sec-WebSocket-Version: 13' \ -H 'Sec-WebSocket-Key: '"$(echo -n $RANDOM | base64)" \ localhost:8000/ws .. code-block:: text GET /ws HTTP/1.1 Connection: Upgrade Upgrade: websocket Host: localhost:8000 Origin: https://localhost:8000 Sec-WebSocket-Version: 13 Sec-WebSocket-Key: s65VsgHigh7v/Jcf4nXHnA== X-Auth-Token: ffedf49d **Example response**: .. code-block:: text HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: mWZjBV9FCglzn1rIKJAxrTFlnJE= Sec-WebSocket-Version: 13 An authentication token **may optionally** be passed as part of the URL for browsers that cannot be configured to send the authentication header or cookie: .. code-block:: bash curl -NsS <...snip...> localhost:8000/ws/ffedf49d The event stream can be easily consumed via JavaScript: .. code-block:: javascript // Note, you must be authenticated! var source = new Websocket('ws://localhost:8000/ws/d0ce6c1a'); source.onerror = function(e) { console.debug('error!', e); }; source.onmessage = function(e) { console.debug(e.data); }; source.send('websocket client ready') source.close(); Or via Python, using the Python module `websocket-client <https://pypi.python.org/pypi/websocket-client/>`_ for example. .. code-block:: python # Note, you must be authenticated! from websocket import create_connection ws = create_connection('ws://localhost:8000/ws/d0ce6c1a') ws.send('websocket client ready') # Look at https://pypi.python.org/pypi/websocket-client/ for more # examples. while listening_to_events: print ws.recv() ws.close() Above examples show how to establish a websocket connection to Salt and activating real time updates from Salt's event stream by signaling ``websocket client ready``. Nr2 r3 c s� |� � tjjjd�jd �jdd��N}|jddd�}t�| �}dd� }t � t j |� t |�}|r`z d� v r@|� |��j� n| � d tjj�|�� d �d � W n ty_ t�d |� Y nw q,1 sdw Y d S )zX An iterator to return Salt events (and optionally format them) r r Tr r c S s t �d� d S )Nr )�os�_exit)�signal�framer r r �signal_handler+ s zCWebsocketEndpoint.GET.<locals>.event_stream.<locals>.signal_handlerZ format_eventsr r Fz(Error: Salt event has non UTF-8 data: %sN)�recvrX rb r r r� r r �SaltInfor �SIGTERMr� �process�sendr� r rz r) r0 )rF �piper r r r r� �rf r� r� r r � event_stream s< � �� ����z+WebsocketEndpoint.GET.<locals>.event_stream)�targetre )r r5 r r r� Zget_tokr r� r Z ws_handlerr r r� r r� ) r� r2 rf r rR rF r" Z parent_pipeZ child_pipe�procr r! r r9 � s e % zWebsocketEndpoint.GETr� ) r� r� r� r� r� rT r� r� r r r� r9 r r r r r � s" ���r c @ sD e Zd ZdZdZg d�Zeejfi ddd���Zdd� Z dd� Z d S ) �Webhooka� A generic web hook entry point that fires an event on Salt's event bus External services can POST data to this URL to trigger an event in Salt. For example, Amazon SNS, Jenkins-CI or Travis-CI, or GitHub web hooks. .. note:: Be mindful of security Salt's Reactor can run any code. A Reactor SLS that responds to a hook event is responsible for validating that the event came from a trusted source and contains valid data. **This is a generic interface and securing it is up to you!** This URL requires authentication however not all external services can be configured to authenticate. For this reason authentication can be selectively disabled for this URL. Follow best practices -- always use SSL, pass a secret key, configure the firewall to only allow traffic from a known source, etc. The event data is taken from the request body. The :mailheader:`Content-Type` header is respected for the payload. The event tag is prefixed with ``salt/netapi/hook`` and the URL path is appended to the end. For example, a ``POST`` request sent to ``/hook/mycompany/myapp/mydata`` will produce a Salt event with the tag ``salt/netapi/hook/mycompany/myapp/mydata``. The following is an example ``.travis.yml`` file to send notifications to Salt of successful test runs: .. code-block:: yaml language: python script: python -m unittest tests after_success: - | curl -sSk https://saltapi-url.example.com:8000/hook/travis/build/success -d branch="${TRAVIS_BRANCH}" -d commit="${TRAVIS_COMMIT}" .. seealso:: :ref:`events`, :ref:`reactor <reactor>` T)rX r� �hook)r� r� c C sN t jd | _tjjjd| jd | jdd�| _t jd �d�r%d| jd< d S d S ) Nr$ r r Fr r Zwebhook_disable_authr� ) r r r� rX rb r r r r� r� r r r r� � s ��zWebhook.__init__c O s` d� t�| j|��}tjjj}|si }ttjjdd�}t tjj �}| j � |||d�|�}d|iS )aC Fire an event in Salt with a custom event tag and data .. http:post:: /hook :status 200: |200| :status 401: |401| :status 406: |406| :status 413: request body is too large **Example request:** .. code-block:: bash curl -sS localhost:8000/hook \ -H 'Content-type: application/json' \ -d '{"foo": "Foo!", "bar": "Bar!"}' .. code-block:: text POST /hook HTTP/1.1 Host: localhost:8000 Content-Length: 16 Content-Type: application/json {"foo": "Foo!", "bar": "Bar!"} **Example response**: .. code-block:: text HTTP/1.1 200 OK Content-Length: 14 Content-Type: application/json {"success": true} As a practical example, an internal continuous-integration build server could send an HTTP POST request to the URL ``https://localhost:8000/hook/mycompany/build/success`` which contains the result of a build and the SHA of the version that was built as JSON. That would then produce the following event in Salt that could be used to kick off a deployment via Salt's Reactor:: Event fired at Fri Feb 14 17:40:11 2014 ************************* Tag: salt/netapi/hook/mycompany/build/success Data: {'_stamp': '2014-02-14_17:40:11.440996', 'headers': { 'X-My-Secret-Key': 'F0fAgoQjIT@W', 'Content-Length': '37', 'Content-Type': 'application/json', 'Host': 'localhost:8000', 'Remote-Addr': '127.0.0.1'}, 'post': {'revision': 'aa22a3c4b2e7', 'result': True}} Salt's Reactor could listen for the event: .. code-block:: yaml reactor: - 'salt/netapi/hook/mycompany/build/*': - /srv/reactor/react_ci_builds.sls And finally deploy the new build: .. code-block:: jinja {% set secret_key = data.get('headers', {}).get('X-My-Secret-Key') %} {% set build = data.get('post', {}) %} {% if secret_key == 'F0fAgoQjIT@W' and build.result == True %} deploy_my_app: cmd.state.sls: - tgt: 'application*' - arg: - myapp.deploy - kwarg: pillar: revision: {{ revision }} {% endif %} �/r| ru )rC Zpostr �success) rB � itertools�chain�tag_baser rE r r� �getattrrT r r Z fire_event)r� re rf r r� r| r rg r r r r: � s T �z Webhook.POSTN) r� r� r� r� r� r+ rT r� r� r� r: r r r r r% I s ,��� r% c @ s: e Zd ZdZdZeejfi ddi��Zdd� Zdd� Z dS ) �Statsz: Expose statistics on the running CherryPy server Tr� c C s" t jd �d�rd| jd< d S d S )Nr Zstats_disable_authFr� )r r r r� r� r r r r� � s �zStats.__init__c C s t td�r t�tj�S i S )aY Return a dump of statistics collected from the CherryPy server .. http:get:: /stats :reqheader X-Auth-Token: |req_token| :reqheader Accept: |req_accept| :resheader Content-Type: |res_ct| :status 200: |200| :status 401: |401| :status 406: |406| � statistics)r^ �loggingr Zextrapolate_statisticsr. r� r r r r9 � s z Stats.GETN) r� r� r� r� r� rT r� r� r� r9 r r r r r- � s r- c @ s e Zd ZdZdZdd� ZdS )�Appz# Class to serve HTML5 apps Tc G s> t jd }tj�tj�tj�t�d��}t jj � |� d|��S )a: Serve a single static file ignoring the remaining path This is useful in combination with a browser-based app using the HTML5 history API. .. http:get:: /app :reqheader X-Auth-Token: |req_token| :status 200: |200| :status 401: |401| r z index.htmlr ) r r r �path�abspathrB �dirname�__file__r �staticZ serve_filer )r� re r Z default_indexr r r r9 s �zApp.GETN)r� r� r� r� r� r9 r r r r r0 s r0 c @ sJ e Zd ZdZeeeeee e e e e d� Zdd� Zdd� Zdd� Zd d � Zd S ) �APIzI Collect configuration and URL map for building the CherryPy app ) �index�login�logoutr2 �minionsr� r� �keys�eventsZstatsc sX | j �dd�du rg d�� ng � � fdd�| j�� D �}|D ] \}}t| ||� � q dS )z� Set an attribute on the local instance for each key/val in url_map CherryPy uses class attributes to resolve URLs. Zenable_sessionsTF)r8 r9 r: r� c 3 s$ � | ] \}}|� vr||fV qd S r� r )rP �url�cls�r r r � <genexpr>M s � �z'API._setattr_url_map.<locals>.<genexpr>N)r r �url_mapr �setattr)r� Zurlsr= r> r r? r �_setattr_url_mapB s � �zAPI._setattr_url_mapc C sX t r | j�dti� | j�| j�dd��d�ti� | j�| j�dd��d�ti� dS )z; Assemble any dynamic or configurable URLs �wsZ webhook_urlr& r' r r N) �HAS_WEBSOCKETSrA r� r r r �lstripr% r0 r� r r r �_update_url_mapT s �$zAPI._update_url_mapc C s, t jd | _t jd | _| �� | �� d S r� )r r r� r rG rC r� r r r r� c s z API.__init__c C s@ | j �dd�| j �dd�| j �dd�| j �dd�| j �d d �| j �d d �| j �d d�| j �dd�d�tj�� ddddd�d�}tjj�tj d�dk rU| j �dd�|d d< t rd| j �dd �rdd|d d< d | j v rsd| j d d �|d < | j �d d �d u r�d |d d < d!| j v r�d| j d! d"�|| j �d#d$�< tj � |d � |S )%z� Combine the CherryPy configuration with the rest_cherrypy config values pulled from the master config and return the CherryPy configuration �hostz0.0.0.0�porti@ Z thread_pool�d Z queue_size� �max_request_body_sizei r/ FZlog_access_fileru Zlog_error_file)zserver.socket_hostzserver.socket_portzserver.thread_poolzserver.socket_queue_sizerL r/ zlog.access_filezlog.error_fileT)zrequest.dispatchztools.trailing_slash.onz tools.gzip.onztools.html_override.onztools.cors_tool.on)�globalr' z12.0.0r Zexpire_responsesrM zengine.timeout_monitor.onZ collect_statsr' ztools.cpstats.onZfavicon)ztools.staticfile.onztools.staticfile.filenamez /favicon.ico� productionZ environmentr5 )ztools.staticdir.onztools.staticdir.dirr r ) r r r �dispatchZMethodDispatcherrX rb ZversionsZ version_cmp� __version__r r r� )r� Zconfr r r �get_confj sH � � �� � � �z API.get_confN)r� r� r� r� r� r� r� r� r� r� r� r� r� r- rA rC rG r� rQ r r r r r6 0 s" � r6 c C sD | � t�dd�d i �}| tjd< |tjd< t� }|�� }|||fS )z; Returns a WSGI app and a configuration dictionary �.� ���r$ r )r r� �rsplitr r r6 rQ )r� r �rootZcpyoptsr r r �get_app� s rW )[r� rr r� r) r/ r r r� r �collections.abcr r �multiprocessingr r � urllib.parser r rX Z salt.authZsalt.exceptionsZ salt.netapiZsalt.utils.argsZsalt.utils.eventZsalt.utils.jsonZsalt.utils.stringutilsZsalt.utils.versionsZsalt.utils.yaml� getLoggerr� r) Z cherrypy.libr r{ �warning� ImportErrorru r r� r rE �type�objectr r# r. r1 r7 rG rb r� r �partialr� Z safe_dumprU rl rm rn r� r� r� r� r� r� Z tools_configr r& Z tool_listr� r� Z tool_configZ tool_nameZtool_fnrB ZToolr� r� r� r� r� r� r� r� r� r r% r- r0 r6 rW r r r r �<module> s� N � � �# B 3�� M 3 # ������ 1zq D 7D E (" v
| ver. 1.4 |
Github
|
.
| PHP 8.2.30 | Generation time: 0 |
proxy
|
phpinfo
|
Settings