PROJECT_MOVED -> https://lab.nexedi.com/nexedi/slapos
[slapos.git] / stack / monitor / README.txt
1 * This stack has for purpose to know if all promises, services, custom monitoring scripts went/are ok.
2 * The second purpose of this stack is to implement a zero-knowledge feature : it means you can use its control interface to provide the user with sensible data. It can also let the user change some parameters
3 * It also provides a web interface, to see which promises, services and custom scripts failed. It also provide a rss feed to easily know the actual state of your instance, and to know when it started to went bad. You can also add your own monitoring scripts, or cgi files (or just files) that you would want to check easily using a web interface.
4
5 Implementation :
6 ----------------
7 1/ In the software.cfg of your Software Release, extends the stack
8 2/ In the template that will be copied for the buildout in the instance folder (instance.cfg ?), you have to add these parts:
9 ###Parts to add for monitoring
10   slap-parameters
11   certificate-authority
12   cron
13   cron-entry-monitor
14   cron-entry-rss
15   deploy-index
16   deploy-index-template
17   deploy-monitor-script
18   deploy-rss-script
19   deploy-settings-cgi
20   deploy-status-cgi
21   make-rss
22   monitor-promise
23   setup-static-files
24   certificate-authority
25   public
26   zero-parameters
27   cgi-httpd-wrappers
28   public-symlink
29
30 * If you want to add a custom monitoring script, you can write it (in whatever language you wish) and save it in YOUR_INSTANCE_FOLDER/etc/monitor.
31 The only thing to know, is that if your script successfully passed, do not return or print nothing. If there is a problem, you can print the explanation on stdout or stderr
32
33 * Here are 2 promises that you can add to your instance buildout, to see if it is working (one is ok, not the other) :
34 [google-promise]
35 recipe = slapos.cookbook:check_url_available
36 path = $${directory:promise}/google
37 url = http://www.google.com
38 dash_path = ${dash:location}/bin/dash
39 curl_path = ${curl:location}/bin/curl
40
41 [failing-promise]
42 recipe = slapos.cookbook:check_url_available
43 path = $${directory:promise}/fail
44 url = http://127.0.0.2
45 dash_path = ${dash:location}/bin/dash
46 curl_path = ${curl:location}/bin/curl
47
48
49 CGI Scripts:
50 ------------
51 This stack also provides a web interface, in wich you can execute custom cgi scripts, or just print files. The web link is provided in the published parameters, as for the password that you have to change as soon as possible
52
53 In that interface you will have access to the previous scripts and the RSS feed. You can also add your files/scripts.
54
55 For that, there exists a folder /var/cgi-bin. You should see that directory as a tree having of deep 2. In /var/cgi-bin, you must create only folders, which are called categories. In each category, you can then add your own files.
56
57 The backend system will automatically render the webpage according to the inside structure of the cgi-bin directory. Moreover, it will also let you access to your scripts only if you are logged in : you do not need do do your own authentication system ! 
58
59
60 Notice :
61 --------
62 * /!\A default password is set up at the installation : "passwordtochange". It has to be rewritten in the control interface by the user itself
63 * /!\ If you use the recipe zeroknown, never name a parameter "recipe" or "password". 
64 * The control interface will let you change the values of the options declared in the [public] section of the config file (see zeroknown recipe). Other section's values will just be printed. These values won't be overwritten by buildout.
65 * If you want to allow a user to change a parameter, use the recipe zeroknown, with the buildout section name : "[public]"
66 * If you manually change a parameter, it could take some time for the modifications to be applied (at least 1 or 2 slapgrid-cp)
67 * If you need to change the port of the web interface of the monitoring stack, just create in your software release file a part called [monitor-parameters] and give the new port value to the parameter "port".