Current File : //proc/227033/root/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyo
�
���^c @@ s� d Z d d l m Z m Z m Z d d l Z d d l m Z d d l m
Z
d d l Z d d l Z
d d l Z
e
j j j � Z d d l Z e j e � Z d e j j f d � � YZ d e f d
� � YZ d S( u�%
A Websockets add-on to saltnado
===============================
.. py:currentmodule:: salt.netapi.rest_tornado.saltnado
:depends: - tornado Python module
In order to enable saltnado_websockets you must add websockets: True to your
saltnado config block.
.. code-block:: yaml
rest_tornado:
# can be any port
port: 8000
ssl_crt: /etc/pki/api/certs/server.crt
# no need to specify ssl_key if cert and key
# are in one single file
ssl_key: /etc/pki/api/certs/server.key
debug: False
disable_ssl: False
websockets: True
All Events
----------
Exposes ``all`` "real-time" events from Salt's event bus on a websocket connection.
It should be noted that "Real-time" here means these events are made available
to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
Clients are however assumed to be able to tolerate any network transport related latencies.
Functionality provided by this endpoint is similar to the ``/events`` end point.
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.
Exposes GET method to return websocket connections.
All requests should include an auth token.
A way to obtain obtain authentication tokens is shown below.
.. code-block:: bash
% curl -si localhost:8000/login \
-H "Accept: application/json" \
-d username='salt' \
-d password='salt' \
-d eauth='pam'
Which results in the response
.. code-block:: json
{
"return": [{
"perms": [".*", "@runner", "@wheel"],
"start": 1400556492.277421,
"token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
"expire": 1400599692.277422,
"user": "salt",
"eauth": "pam"
}]
}
In this example the ``token`` returned is ``d0ce6c1a37e99dcc0374392f272fe19c0090cca7`` and can be included
in subsequent websocket requests (as part of the URL).
The event stream can be easily consumed via JavaScript:
.. code-block:: javascript
// Note, you must be authenticated!
// Get the Websocket connection to Salt
var source = new Websocket('wss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7');
// Get Salt's "real time" event stream.
source.onopen = function() { source.send('websocket client ready'); };
// Other handlers
source.onerror = function(e) { console.debug('error!', e); };
// e.data represents Salt's "real time" event data as serialized JSON.
source.onmessage = function(e) { console.debug(e.data); };
// Terminates websocket connection and Salt's "real time" event stream on the server.
source.close();
Or via Python, using the Python module
`websocket-client <https://pypi.python.org/pypi/websocket-client/>`_ for example.
Or the tornado
`client <https://tornado.readthedocs.io/en/latest/websocket.html#client-side-support>`_.
.. code-block:: python
# Note, you must be authenticated!
from websocket import create_connection
# Get the Websocket connection to Salt
ws = create_connection('wss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7')
# Get Salt's "real time" event stream.
ws.send('websocket client ready')
# Simple listener to print results of Salt's "real time" event stream.
# Look at https://pypi.python.org/pypi/websocket-client/ for more examples.
while listening_to_events:
print ws.recv() # Salt's "real time" event data as serialized JSON.
# Terminates websocket connection and Salt's "real time" event stream on the server.
ws.close()
# Please refer to https://github.com/liris/websocket-client/issues/81 when using a self signed cert
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``.
Formatted Events
-----------------
Exposes ``formatted`` "real-time" events from Salt's event bus on a websocket connection.
It should be noted that "Real-time" here means these events are made available
to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
Clients are however assumed to be able to tolerate any network transport related latencies.
Functionality provided by this endpoint is similar to the ``/events`` end point.
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.
Formatted events parses the raw "real time" event stream and maintains
a current view of the following:
- minions
- jobs
A change to the minions (such as addition, removal of keys or connection drops)
or jobs is processed and clients are updated.
Since we use salt's presence events to track minions,
please enable ``presence_events``
and set a small value for the ``loop_interval``
in the salt master config file.
Exposes GET method to return websocket connections.
All requests should include an auth token.
A way to obtain obtain authentication tokens is shown below.
.. code-block:: bash
% curl -si localhost:8000/login \
-H "Accept: application/json" \
-d username='salt' \
-d password='salt' \
-d eauth='pam'
Which results in the response
.. code-block:: json
{
"return": [{
"perms": [".*", "@runner", "@wheel"],
"start": 1400556492.277421,
"token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
"expire": 1400599692.277422,
"user": "salt",
"eauth": "pam"
}]
}
In this example the ``token`` returned is ``d0ce6c1a37e99dcc0374392f272fe19c0090cca7`` and can be included
in subsequent websocket requests (as part of the URL).
The event stream can be easily consumed via JavaScript:
.. code-block:: javascript
// Note, you must be authenticated!
// Get the Websocket connection to Salt
var source = new Websocket('wss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7');
// Get Salt's "real time" event stream.
source.onopen = function() { source.send('websocket client ready'); };
// Other handlers
source.onerror = function(e) { console.debug('error!', e); };
// e.data represents Salt's "real time" event data as serialized JSON.
source.onmessage = function(e) { console.debug(e.data); };
// Terminates websocket connection and Salt's "real time" event stream on the server.
source.close();
Or via Python, using the Python module
`websocket-client <https://pypi.python.org/pypi/websocket-client/>`_ for example.
Or the tornado
`client <https://tornado.readthedocs.io/en/latest/websocket.html#client-side-support>`_.
.. code-block:: python
# Note, you must be authenticated!
from websocket import create_connection
# Get the Websocket connection to Salt
ws = create_connection('wss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7')
# Get Salt's "real time" event stream.
ws.send('websocket client ready')
# Simple listener to print results of Salt's "real time" event stream.
# Look at https://pypi.python.org/pypi/websocket-client/ for more examples.
while listening_to_events:
print ws.recv() # Salt's "real time" event data as serialized JSON.
# Terminates websocket connection and Salt's "real time" event stream on the server.
ws.close()
# Please refer to https://github.com/liris/websocket-client/issues/81 when using a self signed cert
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``.
Example responses
-----------------
``Minion information`` is a dictionary keyed by each connected minion's ``id`` (``mid``),
grains information for each minion is also included.
Minion information is sent in response to the following minion events:
- connection drops
- requires running ``manage.present`` periodically every ``loop_interval`` seconds
- minion addition
- minon removal
.. code-block:: python
# Not all grains are shown
data: {
"minions": {
"minion1": {
"id": "minion1",
"grains": {
"kernel": "Darwin",
"domain": "local",
"zmqversion": "4.0.3",
"kernelrelease": "13.2.0"
}
}
}
}
``Job information`` is also tracked and delivered.
Job information is also a dictionary
in which each job's information is keyed by salt's ``jid``.
.. code-block:: python
data: {
"jobs": {
"20140609153646699137": {
"tgt_type": "glob",
"jid": "20140609153646699137",
"tgt": "*",
"start_time": "2014-06-09T15:36:46.700315",
"state": "complete",
"fun": "test.ping",
"minions": {
"minion1": {
"return": true,
"retcode": 0,
"success": true
}
}
}
}
}
Setup
=====
i ( t absolute_importt print_functiont unicode_literalsNi ( t event_processor( t _check_cors_origint AllEventsHandlerc B@ sG e Z d Z d � Z d � Z e j j d � � Z d � Z d � Z
RS( u(
Server side websocket handler.
c C@ sc t j d � | | _ | j j j | � sI t j d � | j d � d St t | � j | � d S( ut
Check the token, returns a 401 if the token is invalid.
Else open the websocket connection
u In the websocket get methodu) Refusing websocket connection, bad token!i� N(
t logt debugt tokent applicationt autht get_tokt
send_errort superR t get( t selfR ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyR ; s
c C@ s
t | _ d S( um
Return a websocket connection to Salt
representing Salt's "real time" event stream.
N( t Falset connected( R R ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyt openJ s c c@ s� t j d | � | d k r� | j r6 t j d � d St | _ xm t r� y< | j j j | � V} | j t j j
j | d t �� WqB t
k
r� } t j d | � PqB XqB W| j � n d S( u� Listens for a "websocket client ready" message.
Once that message is received an asynchronous job
is stated that yields messages to the client.
These messages make up salt's
"real time" event stream.
u Got websocket message %su websocket client readyu& Websocket already connected, returningNt _json_moduleu; Error! Ending server side websocket connection. Reason = %s( R R R t TrueR t event_listenert get_eventt
write_messaget saltt utilst jsont dumpst _jsont Exceptiont infot close( R t messaget eventt err( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyt
on_messageQ s
c O@ s t j d � | j � d S( u Cleanup.
u In the websocket close methodN( R R R ( R t argst kwargs( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyt on_closep s
c C@ sL | j j } | j d � r2 t t | | d � � St t | � j | � Sd S( uF
If cors is enabled, check that the origin is allowed
u cors_originN( R t mod_optsR t boolR R
R t check_origin( R t originR' ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyR) w s ( t __name__t
__module__t __doc__R R t tornadot gent coroutineR# R& R) ( ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyR 5 s t FormattedEventsHandlerc B@ s e Z e j j d � � Z RS( c c@ s t j d | � | d k r| j r6 t j d � d St | _ t j | � } t j j | j j
� } | j i d d 6d d 6| j d 6d
d 6d d
6d d
6� xg t r y6 | j j
j | � V} | j | | j | j j
� Wq� t k
r} t j d | � Pq� Xq� W| j � n d S( u� Listens for a "websocket client ready" message.
Once that message is received an asynchronous job
is stated that yields messages to the client.
These messages make up salt's
"real time" event stream.
u Got websocket message %su websocket client readyu& Websocket already connected, returningNu grains.itemsu funu *u tgtu tokenu clientu modeu local_asyncu asynchronousu localu; Error! Ending server side websocket connection. Reason = %s( R R R R R t SaltInfoR t netapit NetapiClientR t optst runR R R t processR R ( R R t
evt_processort clientR! R" ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyR# � s0
( R+ R, R. R/ R0 R# ( ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyR1 � s ( R- t
__future__R R R t tornado.websocketR. t R t saltnadoR t tornado.gent salt.utils.jsonR t salt.netapiR R t import_jsonR t loggingt getLoggerR+ R t websockett WebSocketHandlerR R1 ( ( ( sP /usr/lib/python2.7/site-packages/salt/netapi/rest_tornado/saltnado_websockets.pyt <module># s O
Mini Shell