Package: halite
======Halite======(Code-name) Halite is a Salt GUI. Status is pre-alpha. Contributions arevery welcome. Join us in #salt on Freenode or on the salt-users mailinglist.For best results it is recommended to use Halite with the develop branch of Salt.Halite is, however, known to work with Salt version greater than ``Hydrogen``.To install the develop branch of Salt:.. code-block:: bash$ git clone -b develop https://github.com/saltstack/salt.git$ cd salt && python setup.py install$ salt-master --version$ salt-master -l debugThis version of Halite is designed to work out of the box with SaltStack whenthe PyPi package version of Halite is installed. The PyPi (PIP) version of Haliteis a minified version tailored for this purpose. (https://pypi.python.org/pypi/halite)Halite makes use of the ``Bottle`` (WSGI) web framework. Servers that are tested andknown to work with Halite are ``paste``, ``cherrypy`` and ``gevent``.To pip install Halite... code-block:: bash$ pip install -U haliteThis purpose of ths repository is to enable development of custom versions of theUI that could be deployed with different servers, different configurations, etcand also for development of future features for the Salt packaged version.Features========Highstate Consistency Check---------------------------Halite can poll for highstate consistency. This is similar to executing``salt \* state.highstate test=True`` and checking for the results.Polling is turned ``OFF`` by default.To switch polling on navigate to the preferences tab and check``highStateCheck.performCheck``. The poll timer can be adjusted using``highStateCheck.intervalSeconds`` and is set to 300 Seconds (5 minutes) bydefault. Once these settings are updated click ``Update`` and reload the page.These options are depicted in the screenshot below... image:: screenshots/HighstatePollSettings.pngHighstate consistency check results can be seen on the minion view. Minionsthat have inconsistent state have a flag next to them as shown in the screenshot... image:: screenshots/MinionWithFlag.pngThe ``Highstate`` subtab for each minion displays the state items that lackconsistency. All of the inconsistent items will be displayed here for easyvisualization. The screenshot below shows a message that might appearwhen highstate consistency is disturbed... image:: screenshots/HighstateSubtab.pngThe cog icon that appears in the ``Monitor`` section can be clicked to performhighstate consistency check. The on demand check only works in thescenario where polling is off. In the case where polling is switched on (asdiscussed above) the cog icon will appear to be spinning (and does not respondto clicks)... image:: screenshots/HighstateCheckCog.pngInstallation quickstart=======================This section explains installation of the ``devlopment`` version of Halite.If you are interested in installing Halite as an end user, please follow the`tutorial<http://docs.saltstack.com/topics/tutorials/halite.html>`_ instead.* Setup permissions for users who will use HaliteFor example in master config:.. code-block:: bashexternal_auth:pam:myusername:- .*- '@runner'- '@wheel'Halite uses the runner ``manage.present`` to get the status of minions so runnerpermissions are required.  Currently Halite allows but does not require anywheel modules.* Clone the Halite repository::.. code-block:: bashgit clone https://github.com/saltstack/halite* Run halite/halite/server_bottle.py (use with -h option to get parameters)The simplest approach is to run the server with it dynamically generatingthe main web app load page (main.html) in coffescript mode, where the coffeescriptis transpiled to javascript on the fly. In each case the appropriate server packagemust be installed... code-block:: bash$ ./server_bottle.py -d -C -l debug -s cherrypy$ ./server_bottle.py -d -C -l debug -s paste$ ./server_bottle.py -d -C -l debug -s gevent* Navigate html5 compliant browser to http://localhost:8080/app* LoginThe default eauth method is 'pam'. To change go to the preferences page.Documentation=============Preferences-----------The navbar has a login form. Enter the eauth username and password to login to salt... image:: screenshots/LoggedOut.pngOnce logged in, the navbar will display the username highlighted in blue and a logout button.To logout click on the logout button... image:: screenshots/LoggedIn.pngClick on the SaltStack logo to go to the preferences page.. image:: screenshots/Preferences.pngOn this page one can change the eauth method to something other than 'pam' suchas 'ldap'.Check ``fetchGrains`` if you want grains data to be loaded when Halite loads.Checking ``preloadJobCache`` will fetch all previously completed, cached jobs.Once all changes are made click ``Update`` and refresh the browser page.Commands----------To navigate to the console view click on the 'console' tab... image:: screenshots/HomeConsole.pngThis view has two sections. The ``Command`` section and the ``Monitor`` section.The ``Command`` section is collapsed by default. Clicking on the downward chevron willexpand the ``Command`` section.The top section of the Console view has controls for entering basic salt commands.The target field will target minions with the command selected. There is ping buttonwith the bullhorn icon and the action menu has some preselected common commands.Expanded Commands-----------------.. image:: screenshots/CommandForm.pngClick on the downward chevron button to expand the ``Command`` form with additionalfields for entering any salt module function. To enter "runner" functions prepend"runner." to the function name. For example, "runner.manage.status". To enter wheelfunctions prepend "wheel." to the wheel function name. For example, "wheel.config.values".For commands that require arguments enter them in the arguments fields. The number of argumentfields equals the number of arguments accepted by the function.Click on the Execute button or press the Return key to execute the command.You can choose the ``Target Format`` which will be used by the ``Target`` field to target minions.There is a ping button with the bullhorn icon and the Macro menu has some preselected commandsfor "speed dial".There is also a history feature which appears as a book icon on the top right corner of the ``Command`` panel.Checking ``Live Doc Search`` will show the documentation related to the command beingentered in the ``Function`` field. Un-check it to conserve screen real estate.Monitors---------The bottom section of the console view has monitor view buttons. Each button willshow panels with the associated information.* Command MonitorShows panels, one per command that has been executed by this user on this console.Clicking on the dropdown button will show the associated job ids that have beenrun with this command and the  completion status via an icon.Red is fail, Green is success.Clicking on the button on the panel will rerun the command... image:: screenshots/CommandMonitor.png* Job MonitorShows panels, one per job that has been run by any minion associated with thismaster. Clicking on the associated dropdown button with expand to show Result and Event data.Selecting the result button will show the returner and return datafor each minion targeted by the job... image:: screenshots/JobMonitor.pngSelecting the Event button will show the events associated with the job... image:: screenshots/JobMonitorEvent.png* Minion MonitorShows panels, one per minion that have keys associated with this master. The minionpanels have icons to show the up/down status of the minion and the grains status.Selecting dropdown buttons will show grains data as well as minion (not job) generated events... image:: screenshots/MinionMonitor.pngWith the grains button selected one can see all the grains for the minion... image:: screenshots/MinionGrains.png* Event MonitorShows panels, one per event associated with this Master... image:: screenshots/EventMonitor.pngMore details coming. TBDBrowser requirements--------------------Support for ES5 and HTML5 is required. This means any modern browser or IE10+.Server requirements-------------------* The static media for this app is server-agnostic and may be served from anyweb server at a configurable URL prefix.* This app uses the HTML5 history API.Libraries used--------------Client side web application requirements:* AngularJS framework (http://angularjs.org/)* Bootstrap layout CSS (http://twbs.github.io/bootstrap/)* AngularUI framework (http://angular-ui.github.io/)* Underscore JS module (http://underscorejs.org/‎)* Underscore string JS module (http://epeli.github.io/underscore.string/)* Font Awesome Bootstrap Icon Fonts  (http://fortawesome.github.io/Font-Awesome/)* CoffeeScript Python/Ruby like javascript transpiler (http://coffeescript.org/)* Karma Test Runner (http://karma-runner.github.io/0.8/index.html)* Jasmine unit test framework (http://pivotal.github.io/jasmine/)* Protractor E2E test framework for angular apps (https://github.com/angular/protractor)Optional dependencies:* Cherrypy web server (http://http://www.cherrypy.org/)* Paste web server (http://pythonpaste.org/)* Gevent web server(http://www.gevent.org/)For nodejs testing:* Express javascript web serverDeployment-------------There are two approaches to deploying Halite.1) Use it from Salt.The 0.17 release of salt will run halite automatically if the Halite package isinstalled. So for example after installing SaltStack one can install the Halitepython package with.. code-block:: bash$ pip install -U haliteConfigure the master config for halite as follows... code-block:: bashhalite:level: 'debug'server: 'cherrypy'host: '0.0.0.0'port: '8080'cors: Falsetls: Truecertpath: '/etc/pki/tls/certs/localhost.crt'keypath: '/etc/pki/tls/certs/localhost.key'pempath: '/etc/pki/tls/certs/localhost.pem'The "cherrypy" and "gevent" servers require the certpath and keypath files to run tls/ssl.The .crt file holds the public cert and the .key file holds the private key. Whereasthe "paste" server requires a single .pem file that contains both the cert and key.This can be created simply by concatenating the .crt and .key files.If you want to use a self signed cert you can create one using the Salt .tls module.. code-block:: bashsalt '*' tls.create_ca_signed_cert test localhostWhen using self signed certs, browsers will need approval before accepting the cert.If the web application page has been cached with a non https version of the app thenthe browser cache will have to be cleared before it will recognize and prompt toaccept the self signed certificate.You will also need to configure the eauth method to be used by users of the WUI.See quickstart above for an example.Install the appropriate http wsgi server selected in the master config above. Inthis case its "cherrypy". The other tested servers are "paste" and "gevent". The servermust be multi-threaded, asynchronous, or multi-processing in order to supportthe Server Sent Event streaming connnection used by the WUI.Restart the SaltStack Master and navigate your html5 compliant browser tohttps://localhost:8080/app or however you have configured your master above.If you have problems look for "Halite:" in the saltstack master log output.Customized Deployment====The Halite github repository provides a skeleton framework for building your own customdeployment. One can run the default bottle.py framwork form the command line thusly.. code-block:: bash$ ./server_bottly.py -g$ ./server_bottle.py -s cherrypyor from a python application.. code-block:: pythonimport halitehalite.start()The full set of options is given by.. code-block:: bash$ ./server_bottle.py -husage: server_bottle.py [-h] [-l {info,debug,critical,warning,error}][-s SERVER] [-a HOST] [-p PORT] [-b BASE] [-x] [-t][-c CERT] [-k KEY] [-e PEM] [-g] [-f LOAD] [-C] [-d]Runs localhost web application wsgi service on given host address and port.Default host:port is 0.0.0.0:8080. (0.0.0.0 is any interface on localhost)optional arguments:-h, --help            show this help message and exit-l {info,debug,critical,warning,error}, --level {info,debug,critical,warning,error}Logging level.-s SERVER, --server SERVERWeb application WSGI server type.-a HOST, --host HOST  Web application WSGI server ip host address.-p PORT, --port PORT  Web application WSGI server ip port.-b BASE, --base BASE  Base Url path prefix for client side web application.-x, --cors            Enable CORS Cross Origin Resource Sharing on server.-t, --tls             Use TLS/SSL (https).-c CERT, --cert CERT  File path to tls/ssl cacert certificate file.-k KEY, --key KEY     File path to tls/ssl private key file.-e PEM, --pem PEM     File path to tls/ssl pem file with both cert and key.-g, --gen             Generate web app load file. Default is 'app/main.html'or if provided the file specified by -f option.-f LOAD, --load LOAD  Filepath to save generated web app load file upon -goption.-C, --coffee          Upon -g option generate to load coffeescript.-d, --devel           Development mode.The http server provides two functions.1) Provide content delivery network for the base load of the web application staticcontent such as html and javascript files.2) Provide dynamic rest api interface to salt/client/api.py module that is used bythe web application via ajax and SSE connections. Because SSE and CORS(Cross Origin Resource Sharing is not univesally supported even among HTML5 compliantbrowsers, a single server serves both the static content and the rest API).An alternative approach would be to to use a web socket to stream the events.This would not require CORS. This may bea future option for Halite.To deploy with apache, modify server_bottle.startServer so it creates the app butdoes not call bottle.run on it but returns it to MOD_WSGI.See (http://bottlepy.org/docs/dev/deployment.html) for other details in using bottle.pywith Apache and Mod_wsgi.To do a custom deployment with some other framework like Django etc. would involvereplicating the endpoints from server_bottle.Architecture-------------The following diagram illustrates how the various pieces to Halite interact... image:: diagrams/HaliteArchitecture.pngTesting-------To run the karma jasmine ``unit test`` runner.. code-block:: bash$ cd halite$ karma start karma_unit.conf.jsTo run the protractor ``e2e test`` runner first start up a web server. More informationabout using protractor can be found on their website.Make sure that the end to end test is setup to login to Halite.. code-block:: bash$ vim halite/test/spec-e2e/credentials.coffeeIn that file change the following.. code-block:: coffeescriptlogin =username: 'your_halite_username'password: 'your_halite_password'Now you can run the tests using the following commands.Make sure you have the ``webdriver-manager`` started.More info can be found on the `Protractor <https://github.com/angular/protractor>`_webpage... code-block:: bash$ cd halite$ protractor protractor.conf.jsTo run the ``functional`` tests make sure you have the Python ``webtest``and ``nose`` modules installed.Enter your credentials and the minion name in a new file called``halite/test/functional/config/override.conf``.. code-block:: python[login]username = your_user_namepassword = your_password[minions]apache = minion_connected_to_this_masterThe functional tests can be run via ``nose``... code-block:: bash$ cd halite$ nosetestsYou might have to build the distribution (for development).. code-block:: bash$ cd halite$ ./prep_dist.pySubtree can be fetched by running ``git subtree pull --prefix=halite/lattice lattice master --squash``.. .............................................................................. _`halite`: https://github.com/saltstack/halite