diff --git a/doc/source/01_introduction/about.rst b/doc/source/01_introduction/about.rst index 4b41d79639..39f6658a15 100644 --- a/doc/source/01_introduction/about.rst +++ b/doc/source/01_introduction/about.rst @@ -52,7 +52,7 @@ Shinken has a lot of featuress, we started to list some of them in the last para * Integration with web user interfaces: - * WebUI (Shinken's own UI) + * WebUI (Shinken own User Interface: https://github.com/shinken-monitoring/mod-webui/wiki) * Thruk * Adagios * Multisite diff --git a/doc/source/07_advanced/distributed.rst b/doc/source/07_advanced/distributed.rst index b52b0e3981..c5cda903fd 100644 --- a/doc/source/07_advanced/distributed.rst +++ b/doc/source/07_advanced/distributed.rst @@ -1,26 +1,26 @@ .. _advanced/distributed: ======================== - Distributed Monitoring + Distributed Monitoring ======================== -Introduction +Introduction ============= Shinken can be configured to support distributed monitoring of network services and resources. Shinken is designed for it in contrast to the Nagios way of doing it: which is more of a "MacGyver" way. -Goals +Goals ====== The goal in the distributed monitoring environment is to offload the overhead (CPU usage, etc.) of performing and receiving service checks from a "central" server onto one or more "distributed" servers. Most small to medium sized shops will not have a real need for setting up such an environment. However, when you want to start monitoring thousands of hosts (and several times that many services) using Shinken, this becomes quite important. -The global architecture +The global architecture ======================== -Shinken's architecture has been designed according to the Unix Way: one tool, one task. Shinken has an architecture where each part is isolated and connects to the others via standard interfaces. Shinken is based on the a HTTP backend. This makes building a highly available or distributed monitoring architecture quite easy. In contrast, the Nagios daemon does nearly everything: it loads the configuration, schedules and launches checks, and raises notifications. +Shinken's architecture has been designed according to the Unix Way: one tool, one task. Shinken has an architecture where each part is isolated and connects to the others via standard interfaces. Shinken is based on the a HTTP backend. This makes building a highly available or distributed monitoring architecture quite easy. In contrast, the Nagios daemon does nearly everything: it loads the configuration, schedules and launches checks, and raises notifications. Major innovations of Shinken over Nagios are to : * split the different roles into separate daemons @@ -29,13 +29,13 @@ Major innovations of Shinken over Nagios are to : Shinken core uses **distributed** programming, meaning a daemon will often do remote invocations of code on other daemons, this means that to ensure maximum compatibility and stability, the core language, paths and module versions **must** be the same everywhere a daemon is running. -Shinken Daemon roles +Shinken Daemon roles ===================== * **Arbiter**: The arbiter daemon reads the configuration, divides it into parts (N schedulers = N parts), and distributes them to the appropriate Shinken daemons. Additionally, it manages the high availability features: if a particular daemon dies, it re-routes the configuration managed by this failed daemon to the configured spare. Finally, it receives input from users (such as external commands from nagios.cmd) or passive check results and routes them to the appropriate daemon. Passive check results are forwarded to the Scheduler responsible for the check. There can only be one active arbiter with other arbiters acting as hot standby spares in the architecture. * Modules for data collection: NSCA, TSCA, Ws_arbiter (web service) - * Modules for configuration data storage: MongoDB, + * Modules for configuration data storage: MongoDB, * Modules for status retention: PickleRententionArbiter * Modules for configuration manipulation: IP_Tag, MySQLImport, GLPI, vmware autolinking and other task specific modules @@ -55,21 +55,21 @@ Shinken Daemon roles * **Reactionner**: The reactionner daemon issues notifications and launches event_handlers. This centralizes communication channels with external systems in order to simplify SMTP authorizations or RSS feed sources (only one for all hosts/services). There can be many reactionners for load-balancing and spare roles * Module for external communications: AndroidSMS - * **Broker**: The broker daemon exports and manages data from schedulers. The management can is done exclusively with modules. Multiple :ref:`Broker modules ` can be enabled simultaneously. + * **Broker**: The broker daemon exports and manages data from schedulers. The management is done exclusively with modules. Multiple :ref:`Broker modules ` can be enabled simultaneously. * Module for centralizing Shinken logs: Simple-log (flat file) - * Modules for data retention: Pickle , ToNdodb_Mysql, ToNdodb_Oracle, couchdb + * Modules for data retention: Pickle , ToNdodb_Mysql, ToNdodb_Oracle, couchdb * Modules for exporting data: Graphite-Perfdata, NPCDMOD(PNP4Nagios) and Syslog * Modules for the Livestatus API - status retention and history: SQLite (default), MongoDB (experimental) - * Modules for the Shinken WebUI: GRAPHITE_UI, PNP_UI. Trending and data visualization. - * Modules for compatibility: Service-Perfdata, Host-Perfdata and Status-Dat + * Modules for the Shinken WebUI: Graphite-UI, PNP-UI. Trending and data visualization. + * Modules for compatibility: Service-Perfdata, Host-Perfdata and Status-Dat * **Receiver** (optional): The receiver daemon receives passive check data and serves as a distributed passive command buffer that will be read by the arbiter daemon. There can be many receivers for load-balancing and hot standby spare roles. The receiver can also use modules to accept data from different protocols. Anyone serious about using passive check results should use a receiver to ensure that when the arbiter is not available (when updating a configuration) all check results are buffered by the receiver and forwarded when the arbiter is back on-line. * Module for passive data collection: :ref:`NSCA `, :ref:`TSCA `, :ref:`Ws_arbiter (web service) ` -This architecture is fully flexible and scalable: the daemons that require more performance are the poller and the schedulers. The administrator can add as many as he wants. The broker daemon should be on a well provisioned server for larger installations, as only a single broker can be active at one time. A picture is worth a thousand words: +This architecture is fully flexible and scalable: the daemons that require more performance are the poller and the schedulers. The administrator can add as many as he wants. The broker daemon should be on a well provisioned server for larger installations, as only a single broker can be active at one time. A picture is worth a thousand words: .. image:: /_static/images///official/images/shinken-architecture.png @@ -78,7 +78,7 @@ This architecture is fully flexible and scalable: the daemons that require more .. _advanced/distributed#the_smart_and_automatic_load_balancing: -The smart and automatic load balancing +The smart and automatic load balancing ======================================= @@ -98,7 +98,7 @@ This action is done in two parts: .. _advanced/distributed#creating_independent_packs: -Creating independent packs +Creating independent packs --------------------------- @@ -123,7 +123,7 @@ In this example, we will have two packs: .. _advanced/distributed#the_packs_aggregations_into_scheduler_configurations: -The packs aggregations into scheduler configurations +The packs aggregations into scheduler configurations ----------------------------------------------------- @@ -136,16 +136,16 @@ When all relation packs are created, the Arbiter aggregates them into N configur .. _advanced/distributed#the_configurations_sending_to_satellites: -The configurations sending to satellites +The configurations sending to satellites ----------------------------------------- -When all configurations are created, the Arbiter sends them to the N active Schedulers. A Scheduler can start processing checks once it has received and loaded it's configuration without having to wait for all schedulers to be ready(v1.2). For larger configurations, having more than one Scheduler, even on a single server is highly recommended, as they will load their configurations(new or updated) faster. The Arbiter also creates configurations for satellites (pollers, reactionners and brokers) with links to Schedulers so they know where to get jobs to do. After sending the configurations, the Arbiter begins to watch for orders from the users and is responsible for monitoring the availability of the satellites. +When all configurations are created, the Arbiter sends them to the N active Schedulers. A Scheduler can start processing checks once it has received and loaded it's configuration without having to wait for all schedulers to be ready(v1.2). For larger configurations, having more than one Scheduler, even on a single server is highly recommended, as they will load their configurations(new or updated) faster. The Arbiter also creates configurations for satellites (pollers, reactionners and brokers) with links to Schedulers so they know where to get jobs to do. After sending the configurations, the Arbiter begins to watch for orders from the users and is responsible for monitoring the availability of the satellites. .. _advanced/distributed#the_high_availability: -The high availability +The high availability ====================== @@ -156,11 +156,11 @@ The shinken architecture is a high availability one. Before looking at how this .. _advanced/distributed#when_a_node_dies: -When a node dies +When a node dies ----------------- -Nobody is perfect. A server can crash, an application too. That is why administrators have spares: they can take configurations of failing elements and reassign them. For the moment the only daemon that does not have a spare is the Arbiter, but this will be added in the future. The Arbiter regularly checks if everyone is available. If a scheduler or another satellite is dead, it sends its conf to a spare node, defined by the administrator. All satellites are informed by this change so they can get their jobs from the new element and do not try to reach the dead one. If a node was lost due to a network interruption and it comes back up, the Arbiter will notice and ask the old system to drop its configuration. +Nobody is perfect. A server can crash, an application too. That is why administrators have spares: they can take configurations of failing elements and reassign them. For the moment the only daemon that does not have a spare is the Arbiter, but this will be added in the future. The Arbiter regularly checks if everyone is available. If a scheduler or another satellite is dead, it sends its conf to a spare node, defined by the administrator. All satellites are informed by this change so they can get their jobs from the new element and do not try to reach the dead one. If a node was lost due to a network interruption and it comes back up, the Arbiter will notice and ask the old system to drop its configuration. The availability parameters can be modified from the default settings when using larger configurations as the Schedulers or Brokers can become busy and delay their availability responses. The timers are aggressive by default for smaller installations. See daemon configuration parameters for more information on the three timers involved. This can be explained by the following picture : @@ -169,7 +169,7 @@ This can be explained by the following picture : :scale: 90 % -External commands dispatching +External commands dispatching ============================== The administrator needs to send orders to the schedulers (like a new status for passive checks). In the Shinken way of thinking, the users only need to send orders to one daemon that will then dispatch them to all others. In Nagios the administrator needs to know where the hosts or services are to send the order to the right node. In Shinken the administrator just sends the order to the Arbiter, that's all. External commands can be divided into two types : @@ -182,7 +182,7 @@ For each command, Shinken knows if it is global or not. If global, it just sends .. _advanced/distributed#poller_tag: -Different types of Pollers: poller_tag +Different types of Pollers: poller_tag ======================================= @@ -205,7 +205,7 @@ The pollers can be tagged with multiple poller_tags. If they are tagged, they wi .. _advanced/distributed#use_cases: -Use cases +Use cases ---------- @@ -219,12 +219,12 @@ In the first case, it can be useful to have a windows box in a domain with a pol The second case is a classic one: when you have a DMZ network, you need to have a dedicated poller that is in the DMZ, and return results to a scheduler in LAN. With this, you can still have dependencies between DMZ hosts and LAN hosts, and still be sure that checks are done in a DMZ-only poller. -Different types of Reactionners: reactionner_tag +Different types of Reactionners: reactionner_tag ================================================= * :ref:`Use cases ` -Like for the pollers, reactionners can also have 'tags'. So you can tag your host/service or commands with +Like for the pollers, reactionners can also have 'tags'. So you can tag your host/service or commands with "reactionner_tag". If a notification or an event handler uses a "tagged" or "untagged" command in a untagged host/service, it takes the reactionner_tag of this host/service. In a "untaged" host/service, it's the command tag that is taken into account. The reactionners can be tagged with multiple reactionner_tags. If they are tagged, they will only take checks that are tagged, not the untagged ones, unless they defined the tag "None". @@ -234,7 +234,7 @@ Like for the poller case, it's mainly useful for DMZ/LAN or GNU/Linux/Windows ca .. _advanced/distributed#realms: -Advanced architectures: Realms +Advanced architectures: Realms =============================== @@ -256,7 +256,7 @@ We will use a generic term for this site management, **Realms**. .. _advanced/distributed#realms_in_few_words: -Realms in few words +Realms in few words -------------------- @@ -265,7 +265,7 @@ A realm is a pool of resources (scheduler, poller, reactionner and broker) that .. _advanced/distributed#realms_are_not_poller_tags: -Realms are not poller_tags! +Realms are not poller_tags! ---------------------------- @@ -274,16 +274,16 @@ Make sure to undestand when to use realms and when to use poller_tags. * **realms are used to segregate schedulers** * **poller_tags are used to segregate pollers** -For some cases poller_tag functionality could also be done using Realms. The question you need to ask yourself: Is a poller_tag "enough", or do you need to fully segregate a the scheduler level and use Realms. In realms, schedulers do not communicate with schedulers from other Realms. +For some cases poller_tag functionality could also be done using Realms. The question you need to ask yourself: Is a poller_tag "enough", or do you need to fully segregate a the scheduler level and use Realms. In realms, schedulers do not communicate with schedulers from other Realms. -If you just need a poller in a DMZ network, use poller_tag. +If you just need a poller in a DMZ network, use poller_tag. If you need a scheduler/poller in a customer LAN, use realms. .. _advanced/distributed#sub_realms: -Sub realms +Sub realms ----------- @@ -292,7 +292,7 @@ A realm can contain another realm. It does not change anything for schedulers: t .. _advanced/distributed#example_of_realm_usage: -Example of realm usage +Example of realm usage ----------------------- diff --git a/doc/source/08_configobjects/broker.rst b/doc/source/08_configobjects/broker.rst index ac63465cd8..2a13a95ae4 100644 --- a/doc/source/08_configobjects/broker.rst +++ b/doc/source/08_configobjects/broker.rst @@ -1,11 +1,11 @@ .. _configobjects/broker: ================== -Broker Definition +Broker Definition ================== -Description +Description ============ The Broker daemon provides access to Shinken internal data. Its role is to get data from schedulers (like status and logs) and manage them. The management is done by modules. Many different modules exists : export to graphite, export to syslog, export into ndo database (MySQL and Oracle backend), service-perfdata export, couchdb export and more. To configure modules, consult the :ref:`broker module definitions `. @@ -13,26 +13,26 @@ The Broker daemon provides access to Shinken internal data. Its role is to get d The Broker definition is optional. -Definition Format +Definition Format ================== Variables in red are required, while those in black are optional. However, you need to supply at least one optional variable in each definition for it to be of much use. ================= ======================== -define broker{ -broker_name *broker_name* +define broker{ +broker_name *broker_name* address *dns name of ip address* -port *port* -spare //[0/1]// -realm *realm name* -manage_sub_realms *[0,1]* -modules *modules* -} +port *port* +spare //[0/1]// +realm *realm name* +manage_sub_realms *[0,1]* +modules *modules* +} ================= ======================== -Example Definition: +Example Definition: ==================== :: @@ -44,17 +44,18 @@ Example Definition: spare 0 realm All ## Optional - manage_arbiters 1 + manage_arbiters 1 manage_sub_realms 1 timeout 3 ; Ping timeout data_timeout 120 ; Data send timeout max_check_attempts 3 ; If ping fails N or more, then the node is dead - check_interval 60 ; Ping node every minutes manage_sub_realms 1 - modules livestatus,simple-log,webui + check_interval 60 ; Ping node every minutes + manage_sub_realms 1 + modules livestatus,simple-log,webui2 } - -Variable Descriptions + +Variable Descriptions ====================== broker_name @@ -79,4 +80,4 @@ manage_sub_realms This variable is used to define if the broker will take jobs from scheduler from the sub-realms of it's realm. The default value is *1*. modules - This variable is used to define all modules that the broker will load. The main goal ofthe Broker is to give status to theses modules. + This variable is used to define all modules that the broker will load. The main goal of the Broker is to give status to theses modules. diff --git a/doc/source/08_configobjects/contact.rst b/doc/source/08_configobjects/contact.rst index 8757c7dc67..f2e7e3b5a8 100644 --- a/doc/source/08_configobjects/contact.rst +++ b/doc/source/08_configobjects/contact.rst @@ -1,48 +1,48 @@ .. _configobjects/contact: =================== -Contact Definition +Contact Definition =================== -Description +Description ============ A contact definition is used to identify someone who should be contacted in the event of a problem on your network. The different arguments to a contact definition are described below. -Definition Format +Definition Format ================== Bold directives are required, while the others are optional. ================================= ===================================== -define contact{ -**contact_name** ***contact_name*** -alias *alias* -contactgroups *contactgroup_names* -**host_notifications_enabled** **[0/1]** -**service_notifications_enabled** **[0/1]** -**host_notification_period** ***timeperiod_name*** -**service_notification_period** ***timeperiod_name*** -**host_notification_options** **[d,u,r,f,s,n]** -**service_notification_options** **[w,u,c,r,f,s,n]** -**host_notification_commands** ***command_name*** -**service_notification_commands** ***command_name*** -email *email_address* +define contact{ +**contact_name** ***contact_name*** +alias *alias* +contactgroups *contactgroup_names* +**host_notifications_enabled** **[0/1]** +**service_notifications_enabled** **[0/1]** +**host_notification_period** ***timeperiod_name*** +**service_notification_period** ***timeperiod_name*** +**host_notification_options** **[d,u,r,f,s,n]** +**service_notification_options** **[w,u,c,r,f,s,n]** +**host_notification_commands** ***command_name*** +**service_notification_commands** ***command_name*** +email *email_address* pager *pager_number or pager_email_gateway* -address*x* *additional_contact_address* -can_submit_commands [0/1] -is_admin [0/1] -retain_status_information [0/1] -retain_nonstatus_information [0/1] -min_business_impact [0/1/2/3/4/5] +address*x* *additional_contact_address* +can_submit_commands [0/1] +is_admin [0/1] +retain_status_information [0/1] +retain_nonstatus_information [0/1] +min_business_impact [0/1/2/3/4/5] } ================================= ===================================== -Example Definition +Example Definition =================== @@ -67,7 +67,7 @@ Example Definition } -Directive Descriptions +Directive Descriptions ======================= contact_name @@ -81,13 +81,13 @@ contactgroups host_notifications_enabled This directive is used to determine whether or not the contact will receive notifications about host problems and recoveries. Values : - + * 0 = don't send notifications * 1 = send notifications service_notifications_enabled This directive is used to determine whether or not the contact will receive notifications about service problems and recoveries. Values: - + * 0 = don't send notifications * 1 = send notifications @@ -102,7 +102,7 @@ host_notification_commands host_notification_options This directive is used to define the host states for which notifications can be sent out to this contact. Valid options are a combination of one or more of the following: - + * d = notify on DOWN host states * u = notify on UNREACHABLE host states * r = notify on host recoveries (UP states) @@ -111,7 +111,7 @@ host_notification_options service_notification_options This directive is used to define the service states for which notifications can be sent out to this contact. Valid options are a combination of one or more of the following: - + * w = notify on WARNING service states * u = notify on UNKNOWN service states * c = notify on CRITICAL service states @@ -132,32 +132,32 @@ address*x* Address directives are used to define additional “addresses" for the contact. These addresses can be anything - cell phone numbers, instant messaging addresses, etc. Depending on how you configure your notification commands, they can be used to send out an alert o the contact. Up to six addresses can be defined using these directives (*address1* through *address6*). The $CONTACTADDRESS*x*$ :ref:`macro ` will contain this value. can_submit_commands - This directive is used to determine whether or not the contact can submit :ref:`external commands ` to Shinken from the CGIs. Values: - + This directive is used to determine whether or not the contact can submit :ref:`external commands ` to Shinken from the WebUI. Values: + * 0 = don't allow contact to submit commands * 1 = allow contact to submit commands. is_admin This directive is used to determine whether or not the contact can see all object in :ref:`WebUI `. Values: - + * 0 = normal user, can see all objects he is in contact * 1 = allow contact to see all objects retain_status_information This directive is used to determine whether or not status-related information about the contact is retained across program restarts. This is only useful if you have enabled state retention using the :ref:`retain_state_information ` directive. Value : - + * 0 = disable status information retention * 1 = enable status information retention. retain_nonstatus_information This directive is used to determine whether or not non-status information about the contact is retained across program restarts. This is only useful if you have enabled state retention using the :ref:`retain_state_information ` directive. Value : - + * 0 = disable non-status information retention * 1 = enable non-status information retention min_business_impact - This directive is use to define the minimum business criticity level of a service/host the contact will be notified. Please see :ref:`root_problems_and_impacts ` for more details. - + This directive is use to define the minimum business criticity level of a service/host the contact will be notified. Please see :ref:`root_problems_and_impacts ` for more details. + * 0 = less important * 1 = more important than 0 * 2 = more important than 1 diff --git a/doc/source/08_configobjects/host.rst b/doc/source/08_configobjects/host.rst index bdf8a2f7c3..c988c7de36 100644 --- a/doc/source/08_configobjects/host.rst +++ b/doc/source/08_configobjects/host.rst @@ -296,6 +296,7 @@ business_impact_modulations icon_set This variable is used to set the icon in the Shinken Webui. For now, values are only : database, disk, network_service, server + *Note:* In WebUI version 2, this variable is not used anymore maintenance_period Shinken-specific variable to specify a recurring downtime period. This works like a scheduled downtime, so unlike a check_period with exclusions, checks will still be made (no ":ref:`blackout `" times). `announcement`_ diff --git a/doc/source/08_configobjects/service.rst b/doc/source/08_configobjects/service.rst index 65fa83c407..66fd46ef44 100644 --- a/doc/source/08_configobjects/service.rst +++ b/doc/source/08_configobjects/service.rst @@ -382,6 +382,7 @@ business_impact icon_set This variable is used to set the icon in the Shinken Webui. For now, values are only : database, disk, network_service, server + *Note:* In WebUI version 2, this variable is not used anymore maintenance_period Shinken-specific variable to specify a recurring downtime period. This works like a scheduled downtime, so unlike a check_period with exclusions, checks will still be made (no ":ref:`blackout `" times). `announcement`_ diff --git a/doc/source/09_architecture/the-shinken-architecture.rst b/doc/source/09_architecture/the-shinken-architecture.rst index 0d36007446..67f344b821 100644 --- a/doc/source/09_architecture/the-shinken-architecture.rst +++ b/doc/source/09_architecture/the-shinken-architecture.rst @@ -1,11 +1,11 @@ .. _architecture/the-shinken-architecture: ===================== -Shinken Architecture +Shinken Architecture ===================== -Summary +Summary ======== Shinken's architecture has been designed according to the Unix Way: one tool, one task. Shinken has an architecture where each part is isolated and connects to the others via standard interfaces. Shinken is based on a HTTP backend. This makes building a highly available or distributed monitoring architectures quite easy. @@ -40,26 +40,26 @@ Shinken's architecture has been designed according to the Unix Way: one tool, on * Text file management via configuration engines (cfengine, chef, puppet, salt) -Shinken innovative features +Shinken innovative features ============================ Learn more about the :ref:`innovative features of Shinken `. -Shinken data acquisition for monitoring +Shinken data acquisition for monitoring ======================================== Shinken needs plugins to actually gather data. There exists `**thousands** of plugins for every conceivable application`_. Shinken packages the configurations necessary to use common plugins in :ref:`Packs `. Plugins themselves need to be installed by the administrator of the monitoring solution(Shinken will install some common ones for you). This is a great strength and flexibility of Shinken, but also an administrative responsibility to download and install the necessary plugins. -Architecture diagram with all daemons illustrated +Architecture diagram with all daemons illustrated ================================================== .. image:: /_static/images///official/images/shinken-architecture.png :scale: 90 % -Shinken Daemon roles +Shinken Daemon roles ===================== * :ref:`Arbiter `: The arbiter daemon reads the configuration, divides it into parts (N schedulers = N parts), and distributes them to the appropriate Shinken daemons. Additionally, it manages the high availability features: if a particular daemon dies, it re-routes the configuration managed by this failed daemon to the configured spare. Finally, it can receive input from users (such as external commands from nagios.cmd) or passive check results and routes them to the appropriate daemon. Passive check results are forwarded to the Scheduler responsible for the check. There can only be one active arbiter with other arbiters acting as hot standby spares in the architecture. @@ -91,10 +91,10 @@ Shinken Daemon roles * Modules for the Livestatus API - live state, status retention and history: SQLite (default), MongoDB (experimental) * Module for centralizing Shinken logs: Simple-log (flat file) - * Modules for data retention: Pickle , ToNdodb_Mysql, ToNdodb_Oracle, couchdb + * Modules for data retention: Pickle , ToNdodb_Mysql, ToNdodb_Oracle, couchdb * Modules for exporting data: Graphite-Perfdata, NPCDMOD(PNP4Nagios), raw_tcp(Splunk), Syslog - * Modules for the Shinken WebUI: GRAPHITE_UI, PNP_UI. Trending and data visualization. - * Modules for compatibility/migration: Service-Perfdata, Host-Perfdata and Status-Dat + * Modules for the Shinken WebUI: Graphite-UI, PNP-UI. Trending and data visualization. + * Modules for compatibility/migration: Service-Perfdata, Host-Perfdata and Status-Dat * **Receiver** (optional): The receiver daemon receives passive check data and serves as a distributed command buffer. There can be many receivers for load-balancing and hot standby spare roles. The receiver can also use modules to accept data from different protocols. Anyone serious about using passive check results should use a receiver to ensure that check data does not go through the Arbiter (which may be busy doing administrative tasks) and is forwarded directly to the appropriate Scheduler daemon(s). @@ -104,7 +104,7 @@ Shinken Daemon roles .. tip:: The various daemons can be run on a single server for small deployments or split on different hardware for larger deployments as performance or availability requirements dictate. For larger deployments, running multiple Schedulers is recommended, even if they are on the same server. Consult :ref:`planning a large scale Shinken deployment ` for more information. -Learn more about the Shinken Distributed Architecture +Learn more about the Shinken Distributed Architecture ====================================================== The Shinken distributed architecture, more features explained. @@ -117,7 +117,7 @@ The Shinken distributed architecture, more features explained. If you are just starting out, you can continue on with the next tutorial, which will help you :ref:`Configure a web front-end `. -Planning a large scale Shinken deployment +Planning a large scale Shinken deployment ========================================== If you wish to plan a large scale installation of Shinken, you can consult the :ref:`Scaling Shinken ` reference. diff --git a/doc/source/11_integration/graphite.rst b/doc/source/11_integration/graphite.rst index 49e9991581..bc49ae14d1 100644 --- a/doc/source/11_integration/graphite.rst +++ b/doc/source/11_integration/graphite.rst @@ -5,11 +5,11 @@ Use Shinken with Graphite ========================= -Graphite +Graphite ========= * Homepage: `Graphite`_ - * Screenshots: + * Screenshots: * presentation: http://pivotallabs.com/talks/139-metrics-metrics-everywhere * Description: "Graphite is an easy to use scalable time-series database and a web API that can provide raw data for client rendering or server side rendering. It is the evolution of RRDtool." * License: GPL v2 @@ -18,112 +18,127 @@ Graphite * Graphite dedicated forum: https://answers.launchpad.net/graphite -Install graphite +Install graphite ================= The best installation guide is actually `this youtube walkthrough from Jason Dixon`_ (Obfuscurity). There is a `Chef recipe for the above demonstration`_. See http://graphite.readthedocs.org/en/latest/install.html documentation tells what to install but not how to configure Apache and Django. -See `Installing Graphite version 0.9.8`_ example. Just update for version 0.9.10 it is the exact same installation steps. The vhost example also worked for me, while the wsgi examples did not for me. +See `Installing Graphite version 0.9.8`_ example. Just update for version 0.9.10 it is the exact same installation steps. The vhost example also worked for me, while the wsgi examples did not for me. Make sure you set the timezone properly in ''/opt/graphite/webapp/graphite/local_settings.py'', for instance: - + :: TIME_ZONE = 'Europe/Paris' -Using Shinken with Graphite +Using Shinken with Graphite ============================ - + The Shinken Broker module **graphite** is in charge of exporting performance data from Shinken to the Graphite databases. -Configure graphite module +Configure graphite module -------------------------- - + :: define module{ - module_name Graphite-Perfdata + module_name graphite module_type graphite_perfdata - host localhost - port 2003 - templates_path /var/lib/shinken/share/templates/graphite/ + + # Graphite server / port to use + # default to localhost:2003 + #host localhost + #port 2003 + + graphite_data_source shinken + ... } Additional list of options for the :ref:`Graphite export module and more in-depth documentation `. -Enable it +Enable it ---------- -Edit ''/etc/shinken/brokers/broker-master.cfg'' and find the **Broker** object, and add the graphite module to its **modules** line: +Edit ''/etc/shinken/brokers/broker-master.cfg'', and add the graphite module to its **modules** line: + - :: define broker{ broker_name broker-1 [...] - modules Livestatus,Simple-log,WebUI,Graphite-Perfdata + modules livestatus,simple-log,webui2,graphite } -Use it +Use it ------- -With Shinken UI +With Shinken UI ~~~~~~~~~~~~~~~~ -Still in ''/etc/shinken/modules/graphite.cfg'', find the GRAPHITE_UI object and configure the URL to your Graphite install. -If you used a graphite_data_source in the Graphite-Perfdata section, make sure to specify it here as well. - +In ''/etc/shinken/modules/ui-graphite.cfg'', configure the URL to your Graphite install. +If you used a graphite_data_source in the ''graphite.cfg'', make sure to specify it here as well. + :: define module { - module_name GRAPHITE_UI - uri http://monitoring.mysite.com/graphite/ - graphite_data_source shinken + module_name ui-graphite + module_type graphite-webui + + uri http://YOURSERVERNAME:8080/ + graphite_data_source shinken ... } -Then find the WebUI object, and add GRAPHITE_UI to its modules (you'll want to replace PNP_UI): - +Then edit the ''/etc/shinken/modules/webui2.cfg'' file to add *ui-graphite* to the Web UI modules list: + :: define module { - module_name WebUI - modules Apache_passwd, ActiveDir_UI, Cfg_password, GRAPHITE_UI, Mongodb + module_name webui2 + module_type webui2 + + + modules ui-graphite ... } Restart Shinken to take the changes into account. -You have to possibility to use graphite template files. They are located in "templates_path", (from the graphite_webui module) +You have the possibility to use graphite template files. They are located in "templates_path", (from the graphite_webui module) They are file containing graphite urls with shinken contextual variables. -Ex : +Ex : ''${uri}render/?width=586&height=308&target=alias(legendValue(${host}.${service}.'user'%2C%22last%22)%2C%22User%22)&target=alias(legendValue(${host}.${service}.'sys'%2C%22last%22)%2C%22Sys%22)&target=alias(legendValue(${host}.${service}.'softirq'%2C%22last%22)%2C%22SoftIRQ%22)&target=alias(legendValue(${host}.${service}.'nice'%2C%22last%22)%2C%22Nice%22)&target=alias(legendValue(${host}.${service}.'irq'%2C%22last%22)%2C%22IRQ%22)&target=alias(legendValue(${host}.${service}.'iowait'%2C%22last%22)%2C%22I%2FO%20Wait%22)&target=alias(legendValue(${host}.${service}.'idle'%2C%22last%22)%2C%22Idle%22)&fgcolor=000000&bgcolor=FFFFFF)&areaMode=stacked&yMax=100'' is used for check_cpu. Split this string using & as a separator to understand it. It's quite easy. Use graphite uri api doc. -Shinken uses the templates tht matches the check_command, like pnp does. +Shinken uses the templates that matches the check_command, like pnp does. + +.. important:: The suggested configuration below is not final and has just been created, the +documentation needs to be updated for the correct usage of the .graph templates used in WebUI. +There are a number of the already created, see the existing packs to learn how to use them +properly. -.. important:: The suggested configuration below is not final and has just been created, the documentation needs to be updated for the correct usage of the .graph templates used in WebUI. There are a number of the already created, see the existing packs to learn how to use them properly. Sorry for the inconvenience. +Sorry for the inconvenience. -with Thruk +with Thruk ~~~~~~~~~~~ :ref:`Thruk ` offers a proper integration with PNP, but not with Graphite. -Still, you can use graphite with Thruk. Simply use the **action_url** for your service/host to link toward the graphite url you want. Use HOSTNAME and SERVICEDESC macros. +Still, you can use graphite with Thruk. Simply use the **action_url** for your service/host to link toward the graphite url you want. Use HOSTNAME and SERVICEDESC macros. The action_url icon will be a link to the graph in Thruk UI. -For ex : +For ex : '' http://MYGRAPHITE/render/?lineMode=connected&width=586&height=308&_salt=1355923874.899&target=cactiStyle($HOSTNAME$.$SERVICEDESC$.*)&xFormat=%25H%3A%25M&tz=Europe/Paris&bgcolor=DDDDDD&fgcolor=111111&majorGridLineColor=black&minorGridLineColor=grey'' @@ -134,7 +149,7 @@ A change has been pushed in thruk's github to grant Thruk the features it has fo .. important:: The graphite template files feature is not used in Thruk. It is a "shinken UI only" feature. -Enjoy it +Enjoy it --------- Restart shinken-arbiter and you are done. diff --git a/doc/source/11_integration/webui.rst b/doc/source/11_integration/webui.rst index 022375fb67..54d63a2ee5 100644 --- a/doc/source/11_integration/webui.rst +++ b/doc/source/11_integration/webui.rst @@ -5,7 +5,7 @@ Use Shinken with WebUI ====================== -Shinken WebUI +Shinken WebUI ============== Shinken includes a self sufficient Web User Interface, which includes its own web server (No need to setup Apache or Microsoft IIS) @@ -16,202 +16,65 @@ Shinken WebUI is started at the same time Shinken itself does, and is configured :scale: 90 % -* Homepage: http://www.shinken-monitoring.org/ -* Screenshots: http://www.shinken-monitoring.org/screenshots/ +* Homepage: https://github.com/shinken-monitoring/mod-webui/wiki +* Screenshots: https://github.com/shinken-monitoring/mod-webui/wiki * Description: "Shinken WebUI is the default visualization interface. It's designed to be simple and focus on root problems analysis and business impacts." * License: AGPL v3 * Shinken forum: http://www.shinken-monitoring.org/forum/ -Set up the WebUI module +Set up the WebUI module ======================== -Enable the **webui** module in ''modules/webui.cfg'' configuration file that is on the server where your **Arbiter** is installed. +Installing the Shinken **WebUI** is as simple as: :: - define module{ - module_name WebUI - module_type webui - - host 0.0.0.0 ; mean all interfaces of your broker server - port 7767 - - # CHANGE THIS VALUE or someone may forge your cookies - auth_secret TOCHANGE - - # Allow or not the html characters in plugins output - # WARNING: so far, it can be a security issue - allow_html_output 0 - - # Option welcome message - #login_text Welcome to ACME Shinken WebUI. - - #http_backend auto - # ; can be also: wsgiref, cherrypy, paste, tornado, twisted - # ; or gevent. auto means best match in the system. - modules Apache_passwd,ActiveDir_UI,Cfg_password,Mongodb - - # Modules available for the WebUI: - # - # Note: Choose one or more authentication methods. - # - # Apache_passwd: use an Apache htpasswd files for auth - # ActiveDir_UI: use AD for auth and photo collect - # Cfg_password: use passwords in contacts configuration for authentication - # - # PNP_UI: Use PNP graphs in the UI - # GRAPHITE_UI: Use graphs from Graphite - # - # Mongodb: Necessary for enabling user preferences in WebUI - } - -.. important:: Have you changed the **auth_secret** parameter already? No? Do it now! - -.. important:: Also add the webui to the modules in the broker config in brokers/broker-master.cfg. + # Log in with your shinken user account ... + $ shinken install webui2 -.. note:: The web-server handling HTTP Request to the WebUI is a Python process. You *do not need* any web-server (like Apache) to run the WebUI. - - -Authentification modules -========================= - -The WebUI use modules to lookup your user password and allow to authenticate or not. - -By default it is using the **cfg_password_webui** module, which will look into your contact definition for the **password** parameter. - -.. tip:: You need to declare these modules in the **modules** property of WebUI. - - -Shinken contact - cfg_password_webui -------------------------------------- - -The simpliest is to use the users added as Shinken contacts. - -:: - - define module{ - module_name Cfg_password - module_type cfg_password_webui - } + # Install Python dependencies + $ sudo pip install pymongo>=3.0.3 requests arrow bottle==0.12.8 + # By the time, mongodb is also mandatory to store user's parameters and many other information + $ sudo apt-get install mongodb -Apache htpasswd - passwd_webui -------------------------------- + # Declare webui as a broker module + $ vi /etc/shinken/brokers/broker-master.cfg + [...] + modules webui2 + [...] -This module uses an Apache passwd file (htpasswd) as authentification backend. All it needs is the full path of the file (from a legacy Nagios CGI installation, for example). - -:: - - define module{ - module_name Apache_passwd - module_type passwd_webui - - # WARNING: put the full PATH for this value! - passwd /etc/shinken/htpasswd.users - } - - -Check the owner (must be Shinken user) and mode (must be readable) of this file. - -If you don't have such a file you can generate one with the "htpasswd" command (in Debian's "apache2-utils" package), or from websites like `htaccessTools`_. - -.. important:: To be able to log into the WebUI, users also have to be Shinken contacts! So adding an user in this file without adding it in the contacts will have no effect. - - -Active Directory / OpenLDAP - ad_webui ---------------------------------------- - -This module allows to lookup passwords into both Active Directory or OpenLDAP entries. - -:: + $ sudo service shinken restart - define module { - module_name ActiveDir_UI - module_type ad_webui - ldap_uri ldaps://adserver - username user - password password - basedn DC=google,DC=com - - # For mode you can switch between ad (active dir) - # and openldap - mode ad - } +.. important:: You will find more detailed information on this installation page: https://github.com/shinken-monitoring/mod-webui/wiki/Installation -Change "adserver" by your own dc server, and set the "user/password" to an account with read access on the basedn for searching the user entries. - -Change "mode" from "ad" to "openldap" to make the module ready to authenticate against an OpenLDAP directory service. - -You could also find module sample in the modules directory. - - -User photos -~~~~~~~~~~~~ - - -In the WebUI users can see each others photos. - -At this point only the "ad_webui" module allows to import and display photos in the WebUI. There is no configuration: if you add the "ad_webui" module it will import contact photos automatically. +.. note:: The web-server handling HTTP Request to the WebUI is a Python process. You *do not need* any web-server (like Apache) to run the WebUI. -User preferences modules +Web UI configuration ========================= -The WebUI use mongodb to store all user preferences, dashboards and other information. - -To enable user preferences do the following: - - install mongodb - - add "Mongodb" to your WebUI module list as done in the example at the top of this page - - -Metrology graph modules -======================== - -You can link the WebUI so it will present graphs from other tools, like :ref:`PNP4Nagios ` or Graphite. All you need is to declare such modules (there are already samples in the default configuration) and add them in the WebUI **modules** definition. - - -PNP graphs ------------ - -You can ask for a PNP integration with a **pnp_webui** module. Here is its definition: - -:: - - # Use PNP graphs in the WebUI - define module{ - module_name PNP_UI - module_type pnp_webui - uri http://YOURSERVERNAME/pnp4nagios/ ; put the real PNP uri here. YOURSERVERNAME must be changed - ; to the hostname of the PNP server - } - - -Shinken will automatically replace YOURSERVERNAME with the broker hostname at runtime to try and make it work for you, but you MUST change it to the appropriate value. +The Web UI configuration file ''/etc/shinken/modules/webui2.cfg'' is heavily documented to explain the many available parameters. +Please have a look inside the file or read the configuration page in the Wiki: https://github.com/shinken-monitoring/mod-webui/wiki/Configuration -Graphite graphs ----------------- -You can ask for Graphite graphs with the **graphite_ui** definition. -:: +Web UI modules +========================= - define module{ - module_name GRAPHITE_UI - module_type graphite_webui - uri http://YOURSERVERNAME/ ; put the real GRAPHITE uri here. YOURSERVERNAME must be changed - ; to the hostname of the GRAPHITE server - } +In its actual version, the Web UI is self sufficent and not not need extra modules to be installed or configured, it is designed to run 'out of the box'!. +More information on embedded modules is available on the project Wiki: https://github.com/shinken-monitoring/mod-webui/wiki. -Shinken will automatically replace YOURSERVERNAME with the broker hostname at runtime to try and make it work for you, but you MUST change it to the appropriate value. -Use it! +Use it! ======== -The next step is very easy: just access the WebUI URI (something like %%http://127.0.0.1:7767/%%) on log in with the user/password set during the previous part! The default username and password is admin/admin +The next step is very easy: just access the WebUI URI (something like %%http://127.0.0.1:7767/%%) + +Log in with the user/password defined in one of the contact file of your configuration. -.. _htaccessTools: http://www.htaccesstools.com/htpasswd-generator/ diff --git a/doc/source/99_references/shinken.rst b/doc/source/99_references/shinken.rst index 4c367f0260..1e5239f3cb 100644 --- a/doc/source/99_references/shinken.rst +++ b/doc/source/99_references/shinken.rst @@ -669,5 +669,4 @@ Subpackages shinken.discovery shinken.misc shinken.objects - shinken.webui diff --git a/doc/source/99_references/shinken.webui.rst b/doc/source/99_references/shinken.webui.rst deleted file mode 100644 index 3220a77320..0000000000 --- a/doc/source/99_references/shinken.webui.rst +++ /dev/null @@ -1,154 +0,0 @@ -webui Package -============= - -Diagrams ---------- - -Simple ServerAdapter class diagram - -.. inheritance-diagram:: shinken.webui.bottlewebui.ServerAdapter shinken.webui.bottlecore.CGIServer - shinken.webui.bottlecore.FlupFCGIServer shinken.webui.bottlecore.FlupSCGIServer - shinken.webui.bottlecore.WSGIRefServer shinken.webui.bottlecore.WSGIRefServerSelect - shinken.webui.bottlecore.CherryPyServer shinken.webui.bottlecore.PasteServer - shinken.webui.bottlecore.MeinheldServer shinken.webui.bottlecore.FapwsServer - shinken.webui.bottlecore.TornadoServer shinken.webui.bottlecore.AppEngineServer - shinken.webui.bottlecore.TwistedServer shinken.webui.bottlecore.DieselServer - shinken.webui.bottlecore.GeventServer shinken.webui.bottlecore.GunicornServer - shinken.webui.bottlecore.EventletServer shinken.webui.bottlecore.RocketServer - shinken.webui.bottlecore.BjoernServer shinken.webui.bottlecore.AutoServer - shinken.webui.bottlewebui.CGIServer shinken.webui.bottlewebui.FlupFCGIServer - shinken.webui.bottlewebui.FlupSCGIServer shinken.webui.bottlewebui.WSGIRefServer - shinken.webui.bottlewebui.WSGIRefServerSelect shinken.webui.bottlewebui.CherryPyServer - shinken.webui.bottlewebui.PasteServer shinken.webui.bottlewebui.MeinheldServer - shinken.webui.bottlewebui.FapwsServer shinken.webui.bottlewebui.TornadoServer - shinken.webui.bottlewebui.AppEngineServer shinken.webui.bottlewebui.TwistedServer - shinken.webui.bottlewebui.DieselServer shinken.webui.bottlewebui.GeventServer - shinken.webui.bottlewebui.GunicornServer shinken.webui.bottlewebui.EventletServer - shinken.webui.bottlewebui.RocketServer shinken.webui.bottlewebui.BjoernServer - shinken.webui.bottlewebui.AutoServer - :parts: 3 - - -Simple DictProperty class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.DictProperty - :parts: 3 - - - -Simple HooksPlugin class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.HooksPlugin - :parts: 3 - - - -Simple JSONPlugin class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.JSONPlugin - :parts: 3 - - - -Simple HeaderProperty class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.HeaderProperty - :parts: 3 - - - -Simple BaseResponse class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.BaseResponse - :parts: 3 - - - -Simple TemplatePlugin class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.TemplatePlugin - :parts: 3 - - - -Simple BaseTemplate class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.BaseTemplate shinken.webui.bottlecore.MakoTemplate - shinken.webui.bottlecore.CheetahTemplate shinken.webui.bottlecore.SimpleTALTemplate - shinken.webui.bottlecore.SimpleTemplate shinken.webui.bottlewebui.MakoTemplate - shinken.webui.bottlewebui.CheetahTemplate shinken.webui.bottlewebui.SimpleTALTemplate - shinken.webui.bottlewebui.SimpleTemplate - :parts: 3 - - -Simple DictMixin class diagram : - -.. inheritance-diagram:: UserDict.DictMixin shinken.webui.bottlecore.BaseRequest shinken.webui.bottlecore.MultiDict - shinken.webui.bottlecore.HeaderDict shinken.webui.bottlecore.WSGIHeaderDict - shinken.webui.bottlewebui.BaseRequest shinken.webui.bottlewebui.MultiDict - shinken.webui.bottlewebui.HeaderDict shinken.webui.bottlewebui.WSGIHeaderDict - :parts: 3 - - - -Simple Router class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.Router - :parts: 3 - - - -Simple WSGIFileWrapper class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.WSGIFileWrapper - :parts: 3 - - - -Simple Bottle class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.Bottle - :parts: 3 - - - -Simple TypeFilterPlugin class diagram : - -.. inheritance-diagram:: shinken.webui.bottlewebui.TypeFilterPlugin - :parts: 3 - - - -Simple list class diagram : - -.. inheritance-diagram:: __builtin__.list shinken.webui.bottlecore.AppStack shinken.webui.bottlewebui.AppStack - :parts: 3 - - -Package --------- - -:mod:`webui` Package --------------------- - -.. automodule:: shinken.webui - :members: - :undoc-members: - :show-inheritance: - -:mod:`bottlecore` Module ------------------------- - -.. automodule:: shinken.webui.bottlecore - :members: - :undoc-members: - :show-inheritance: - -:mod:`bottlewebui` Module -------------------------- - -.. automodule:: shinken.webui.bottlewebui - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/source/_static/images/Capture-03.JPG b/doc/source/_static/images/Capture-03.JPG new file mode 100644 index 0000000000..1048d6db48 Binary files /dev/null and b/doc/source/_static/images/Capture-03.JPG differ diff --git a/doc/source/_static/images/problems.png b/doc/source/_static/images/problems.png index 69e3c6bfa6..72fff6b30e 100644 Binary files a/doc/source/_static/images/problems.png and b/doc/source/_static/images/problems.png differ diff --git a/doc/source/_static/images/shinken_webui.png b/doc/source/_static/images/shinken_webui.png index fb3213edb1..28f5099827 100644 Binary files a/doc/source/_static/images/shinken_webui.png and b/doc/source/_static/images/shinken_webui.png differ